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INTRODUCTION 



This manual gives the Windows-application developer general as well as 
detailed information about Windows functions, messages, data types, 
Resource Compiler statements, assembly language macros, and file 
formats. This manual provides detailed descriptions of each component 
of the Windows application program interface (API) for readers who 
already have a basic understanding of Windows programming. 

This manual is divided into two volumes. Volume 1 contains reference 
information describing the Windows functions and messages. 

Volume 2 contains reference material for other components of the 
Windows API. It contains the following nine chapters and five 
appendixes: 

Chapter 7, "Data types and structures," contains a table of data types and 
an alphabetical list of structures found in Windows. 

Chapter 8, "Resource script statements," describes the statements that 
define resources which the Resource Compiler adds to an application's 
executable file. The statements are arranged according to functional 
groups. 

Chapter 9, "File formats," describes the formats of five types of files: 
bitmap files, icon resource files, cursor resource files, clipboard files, and 
metafiles. Each description gives the general file structure and 
information about specific parts of the file. 

Chapter 10, "Module-definition statements," describes the statements 
contained in the module-definition file that defines the application's 
contents and system requirements for the LINK program. 

Chapter 11, "Binary and ternary raster-operation codes," describes the 
raster operations used for line output and those used for bitmap output. 

Chapter 12, "Printer escapes," lists the printer escapes that are available 
in Windows. 
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Chapter 13, "Windows DDE protocol definition," contains an alphabetical 
listing and description of the Windows messages that comprise the 
Windows Dynamic Data Exchange protocol. 

Appendix A, "Virtual-key codes," lists the symbolic names and 
hexadecimal values of Windows virtual-key codes and includes a brief 
description of each key. 

Appendix B, "RC Diagnostic messages," contains a listing of Resource 
Compiler error messages and provides a brief description of each 
message. 



Document conventions 



Throughout this manual, the term "DOS" refers to both MS-DOS® and 
PC-DOS, except when noting features that are unique to one or the other. 

The following document conventions are used throughout this manual: 



Convention 



Description 



Bold text 



() 
Italic text 



Monospaced type 



Bold letters indicate a specific term or punctuation mark 
intended to be used literally: language key words or 
functions (such as EXETYPE or CreateWindow), DOS 
commands, and command-line options (such as /Zi). You 
must type these terms and punctuation marks exactly as 
shown. However, the use of uppercase or lowercase letters 
is not always significant. For instance, you can invoke the 
linker by typing either LINK, link, or Link at the DOS 
prompt. 

In syntax statements, parentheses enclose one or more 
parameters that you pass to a function. 

Words in italics indicate a placeholder; you are expected to 
provide the actual value. For example, the following 
syntax for the SetCursorPos function indicates that you 
must substitute values for the X and Y coordinates, 
separated by a comma: 

SetCursorPos(X, Y) 

Code examples are displayed in a nonproportional 
typeface. 

Vertical ellipses in program examples 

indicate that a portion of the program is omitted. 

Ellipses following an item indicate that more items having 
the same form may appear. In the following example, the 



Software development kit 



horizontal ellipses indicate that you can specify more than 
one breakaddress for the g command: 

g [[=startaddress]] [[breakaddress]]. . . 

[[]] Double brackets enclose optional fields or parameters in 

command lines and syntax statements. In the following 
example, option and executable-file are optional parameters 
of the RC command: 

RC [[option]] filename [[executable-file]] 

I A vertical bar indicates that you may enter one of the 

entries shown on either side of the bar. The following 
command-line syntax illustrates the use of a vertical bar: 

DB [[address I range]] 

The bar indicates that following the DB (dump bytes) 
command, you can specify either an address or a range. 

{ } Curly braces indicate that you must specify one of the 

enclosed items. 

SMALL CAPITAL LETTERS Small capital letters indicate the names of keys and key 
sequences, such as: 

ALT + SPACEBAR 

3.0 The Microsoft Windows version number indicates that a 

function, message, or data structure is compatible only 
with the specified version and later versions. 
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ART 



General reference 



Part 3 provides general reference information on components of 
the Windows application programming interface that are in 
addition to the functions and messages described in the preceding 
parts. 
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Data types and structures 



This chapter describes the data types and structures used by Microsoft 
Windows functions and messages. It contains two parts: a table of data 
types and a list of Windows data structures, each arranged alphabetically. 



Data types 



The data types in the following list are key words that define the size and 
meaning of parameters and return values associated with Windows 
functions. This list contains character, integer, and Boolean types, pointer 
types, and handles. The character, integer, and Boolean types are common 
to most C compilers. Most of the pointer-type names begin with either a P 
prefix (for short pointers) or an LP prefix (for long pointers). A short 
pointer accesses data within the current data segment; a long pointer 
contains a 32-bit segment/offset value. A Windows application uses a 
handle to refer to a resource that has been loaded into memory. Windows 
provides access to these resources through internally maintained tables 
that contain individual entries for each handle. Each entry in the handle 
table contains the address of the resource and a means of identifying the 
resource type. The Windows data types are defined in the following list: 



Data type Description 



BOOL 16-bit Boolean value. 

BYTE Unsigned 8-bit integer. 

char ASCII character or a signed 8-bit integer. 



Chapter 7, Data types and structures 



DWORD 

FAR 

FARPROC 

GLOBALHANDLE 

HANDLE 

HBITMAP 

HBRUSH 

HCURSOR 

HDC 

HFONT 

HICON 

HMENU 

HPALETTE 

HPEN 

HRGN 

HSTR 

int 
LOCALHANDLE 

long 

LONG 

LPBITMAP 

LPBITMAPCOREHEADER 

LPBITMAPCOREINFO 

LPBITMAPFILEHEADER 

LPBITMAPINFO 
LPBITMAPINFOHEADER 

LPCOMPAREITEMSTRUCT 

LPCREATESTRUCT 



Unsigned 32-bit integer or a segment/offset 

address. 

Data-type attribute that can be used to create a 

long pointer. 

Long pointer to a function obtained by calling the 

MakeProclnstance function. 

Handle to global memory. It is a 16-bit index to a 

block of memory allocated from the system's 

global heap. 

General handle. It represents a 16-bit index to a 

table entry that identifies program data. 

Handle to a physical bitmap. It is a 16-bit index to 

GDI's physical drawing objects. 

Handle to a physical brush. It is a 16-bit index to 

GDI's physical drawing objects. 

Handle to a cursor resource. It is a 16-bit index to a 

resource-table entry. 

Handle to a display context. It is a 16-bit index to 

GDI's device-context tables. 

Handle to a physical font. It is a 16-bit index to 

GDI's physical drawing objects. 

Handle to an icon resource. It is a 16-bit index to a 

resource-table entry. 

Handle to a menu resource. It is a 16-bit index to a 

resource-table entry. 

Handle to a logical palette. It is a 16-bit index to 

GDI's physical drawing objects. 

Handle to a physical pen. It is a 16-bit index to 

GDI's physical drawing objects. 

Handle to a physical region. It is a 16-bit index to 

GDI's physical drawing objects. 

Handle to a string resource. It is a 16-bit index to a 

resource-table entry. 

Signed 16-bit integer. 

Handle to local memory. It is a 16-bit index to a 

block of memory allocated from the application's 

local heap. 

Signed 32-bit integer. 

Signed 32-bit integer. 

Long pointer to a BITMAP data structure. 

Long pointer to a BITMAPCOREHEADER data 

structure. 

Long pointer to a BITMAPCOREINFO data 

structure. 

Long pointer to a BITMAPFILEHEADER data 

structure. 

Long pointer to a BITMAPINFO data structure. 

Long pointer to a BITMAPINFOHEADER data 

structure. 

Long pointer to a COMPAREITEMSTRUCT data 

structure. 

Long pointer to a CREATESTRUCT data structure. 
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LPDELETEITEMSTRUCT 

LPDRAWITEMSTRUCT 

LPHANDLETABLE 

LPINT 

LPLOGBRUSH 

LPLOGFONT 

LPLOGPALETTE 

LPLOGPEN 

LPMEASUREITEMSTRUCT 

LPMETAFILEPICT 

LPMSG 

LPOFSTRUCT 

LPPAINTSTRUCT 

LPPALETTEENTRY 

LPPOINT 

LPRECT 

LPRESOURCELIST 

LPSTR 

LPTEXTMETRIC 

LPVOID 

LPWNDCLASS 

NEAR 

NPSTR 

PINT 

PSTR 

PWORD 

short 

void 

WORD 



Long pointer to a DELETEITEMSTRUCT data 

structure. 

Long pointer to a DRAWITEMSTRUCT data 

structure. 

Long pointer to a HANDLETABLE data structure. 

Long pointer to a signed 16-bit integer. 

Long pointer to a LOGBRUSH data structure. 

Long pointer to a LOGFONT data structure. 

Long pointer to a LOG PALETTE data structure. 

Long pointer to a LOGPEN data structure. 

Long pointer to a MEASUREITEMSTRUCT data 

structure. 

Long pointer to a METAFILEPICT data structure. 

Long pointer to a MSG data structure. 

Long pointer to an OFSTRUCT data structure. 

Long pointer to a PAINTSTRUCT data structure. 

Long pointer to a PALETTEENTRY data structure. 

Long pointer to a POINT data structure. 

Long pointer to a RECT data structure. 

Long pointer to one or more RESOURCESTRUCT 

data structures. 

Long pointer to a character string. 

Long pointer to a TEXTMETRIC data structure. 

Long pointer to an undefined data type. 

Long pointer to a WNDCLASS data structure. 

Data-type attribute that can be used to create a 

short pointer. 

Near pointer to a character string. 

Pointer to a signed 16-bit integer. 

Pointer to a character string. 

Pointer to an unsigned 16-bit integer. 

Signed 16-bit integer. 

Empty value. It is used with a function to specify 

no return value. 

Unsigned 16-bit integer. 



Data structures 



This section lists data structures that are used by Windows. The data 
structures are presented in alphabetical order. The structure definition is 
given, followed by a description of each field. 
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BITMAP 



BITMAP 











Bitmap 








data 


The BITMAP structure defines the height, width, color format, and bit 


structure 


values of a 


logical bitmap. 






typedef struct tagBITMAP { 


TBitmap = record 




short 


bmType; 


bmType: Integer; 




short 


bmWidth; 


bmWidth: Integer; 




short 


bmHeight; 


bmHeight : Integer; 




short 


bmWidthBytes; 


bmWidthBytes: Integer; 




BYTE 


bmPlanes; 


bmPlanes: Byte; 




BYTE 


bmBitsPixel; 


bmBitsPixel: Byte; 




LPSTR 


bmBits; 


bmBits: Pointer; 




} BITMAP; 




end; 




The BITMAP structure has the 


following fields: 




Field 


Description 





bmType Specifies the bitmap type. For logical bitmaps, the bmType 

field must be zero. 
bmWidth Specifies the width of the bitmap (in pixels). The width must 

be greater than zero. 
bmHeight Specifies the height of the bitmap (in raster lines). The height 

must be greater than zero. 
bmWidthBytes Specifies the number of bytes in each raster line. This value 

must be an even number since the graphics device interface 

(GDI) assumes that the bit values of a bitmap form an array of 

integer (two-byte) values. In other words, bmWidthBytes 8 

must be the next multiple of 16 greater than or equal to the 

bmWidth field. 
bmPlanes Points to the number of color planes in the bitmap. 

bmBitsPixel Points to the number of adjacent color bits on each plane 

needed to define a pixel. 
bmBits Points to the location of the bit values for the bitmap. The 

bmBits field must be a long pointer to an array of character 

(one-byte) values. 

Comments The currently used bitmap formats are monochrome and color. The 
monochrome bitmap uses a one-bit, one-plane format. Each scan is a 
multiple of 16 bits. 

Scans are organized as follows for a monochrome bitmap of height n: 

Scan 
Scan 1 
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BITMAP 



See also 



Scan n-2 
Scan n-1 

The pixels on a monochrome device are either black or white. If the 
corresponding bit in the bitmap is 1, the pixel is turned on (white); if the 
corresponding bit in the bitmap is zero, the pixel is turned off (black). 

All devices that have the RC_BITBLT bit set in the device capabilities 
support bitmaps. 

Each device has its own unique color format. In order to transfer a bitmap 
from one device to another, use GetDIBits and SetDIBits. 

The CreateBitmaplndirect and GetObject functions in Chapter 4, 
"Functions directory," in Reference, Volume 1. 



BITMAPCOREHEADER 



3.0 



Device- 
independent The BITMAPCOREHEADER structure contains information about the 
foitmnn dimensions and color format of a device-independent bitmap that is 

compatible with Microsoft OS/2 Presentation Manager versions 1.1 and 

format 1.2 bitmaps, 
information 



typedef struct tagBITMAPCOREHEADER 



TBitmapCoreHeader = record 

bcSize: Longint;{ used to get to 
color table } 

bcWidth: Word; 

bcHeight: Word; 

bcPlanes: Word; 

bcBitCount: Word; 
end; 

The BITMAPCOREHEADER structure has the following fields: 



DWORD 


bcSize; 


WORD 


bcWidth; 


WORD 


bcHeight; 


WORD 


bcPlanes; 


WORD 


bcBitCount; 


BITMAPCOREHEADER; 



Field 


Description 


bcSize 


Specifies the number of bytes required by the BITMAP- 




COREHEADER structure. 


bcWidth 


Specifies the width of the bitmap in pixels. 


bcHeight 


Specifies the height of the bitmap in pixels. 


bcPlanes 


Specifies the number of planes for the target device and must be 




set to 1. 


bcBitCount 


Specifies the number of bits per pixel. This value must be 1, 4, 8, 




or 24. 
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BITMAPCOREHEADER 



Comments The BITMAPCOREINFO data structure combines the 

BITMAPCOREHEADER structure and a color table to provide a complete 
definition of the dimensions and colors of a device-independent bitmap. 
See the description of the BITMAPCOREINFO data structure for more 
information about specifying a device-independent bitmap. 

An application should use the information stored in the bcSize field to 
locate the color table in a BITMAPCOREINFO data structure with a 
method such as the following: 



pColor = ((LPSTR) pBitmapCorelnfo + 
-» bcSize)) 



(WORD) (pBitmapCorelnfo 



BITMAPCOREINFO 



3.0 



Device- 
independent The BITMAPCOREINFO structure fully defines the dimensions and color 
bitmOD information for a device-independent bitmap that is compatible with 
, , , . Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 bitmaps. 

information 



typedef struct _BITMAPC0REINF0 { 

BITMAPCOREHEADER bmciHeader; 
RGBTRIPLE 

bmciColors[] ; 

} BITMAPCOREINFO; 



TBitmapCorelnfo = record 
bmciHeader: TBitmapCoreHeader; 
bmciColors: array [0..0] of 
TRGBTriple; 

end; 



The BITMAPCOREINFO structure contains the following fields: 

Field Description 

bmciHeader Specifies a BITMAPCOREHEADER data structure that 

contains information about the dimensions and color format 
of a device-independent bitmap. 

bmciColors Specifies an array of RGBTRIPLE data structures that define 

the colors in the bitmap. 

Comments An OS/2 Presentation Manager device-independent bitmap consists of 
two distinct parts: a BITMAPCOREINFO data structure that describes the 
dimensions and colors of the bitmap, and an array of bytes which define 
the pixels of the bitmap. The bits in the array are packed together, but 
each scan line must be zero-padded to end on a LONG boundary. Segment 
boundaries can appear anywhere in the bitmap, however. The origin of 
the bitmap is the lower-left corner. 



12 



Software development kit 



BITMAPCOREINFO 



The bcBitCount field of the BITMAPCOREHEADER structure determines 
the number of bits which define each pixel and the maximum number of 
colors in the bitmap. This field may be set to any of the following values: 

Value Description 

1 The bitmap is monochrome, and the bmciColors field must contain 

two entries. Each bit in the bitmap array represents a pixel. If the bit is 
clear, the pixel is displayed with the color of the first entry in the 
bmciColors table; if the bit is set, the pixel has the color of the second 
entry in the table. 

4 The bitmap has a maximum of 16 colors, and the bmciColors field 

contains 16 entries. Each pixel in the bitmap is represented by a four- 
bit index into the color table. For example, if the first byte in the 
bitmap is OxlF, then the byte represents two pixels. The first pixel 
contains the color in the second table entry, and the second pixel 
contains the color in the 16th table entry. 

.8 The bitmap has a maximum of 256 colors, and the bmciColors field 

contains 256 entries. In this case, each byte in the array represents a 
single pixel. 

24 The bitmap has a maximum of 2 24 colors. The bmciColors field is 

NULL, and each three bytes in the bitmap array represents the relative 
intensities of red, green, and blue, respectively, of a pixel. 

The colors in the bmciColors table should appear in order of importance. 

Alternatively, for functions that use device-independent bitmaps, the 
bmciColors field can be an array of 16-bit unsigned integers that specify 
an index into the currently realized logical palette instead of explicit RGB 
values. In this case, an application using the bitmap must call device- 
independent bitmap functions with the wllsage parameter set to 
DIB_PAL_COLORS. 

The bmciColors field should not contain palette indexes if the bitmap is to 
be stored in a file or transferred to another application. Unless the 
application uses the bitmap exclusively and under its complete control, 
the bitmap color table should contain explicit RGB values. 
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BITMAPFILEHEADER 



BITMAPFILEHEADER 



3.0 



Bitmap file 
information 



The BITMAPFILEHEADER data structure contains information about the 
type, size, and layout of a device-independent bitmap (DIB) file. 



typedef struct tagBITMAPFILEHEADER { 

WORD bfType; 

DWORD bfSize; 

WORD bfReservedl; 

WORD bfReserved2; 

DWORD bfOffBits; 
} BITMAPFILEHEADER; 



TBitmapFileHeader = record 

bfType: Word; 

bfSize: Longint; 

bfReservedl: Word; 

bfReserved2: Word; 

bfOffBits: Longint; 
end; 



The BITMAPFILEHEADER data structure contains the following fields: 





Field 


Description 




bfType 

bfSize 

bfReservedl 

bfReserved2 

bfOffBits 


Specifies the type of file. It must be BM. 

Specifies the size in DWORDs of the file. 

Is reserved and must be set to zero. 

Is reserved and must be set to zero. 

Specifies in bytes the offset from the BITMAPFILEHEADER of 

the actual bitmap in the file. 


Comments 
BITMAPINFO 


A BITMAPINFO or BITMAPCOREINFO data structure immediately follows 
the BITMAPFILEHEADER structure in the DIB file. 

3.0 









Device- 

indGpGndGnt The BITMAPINFO structure fully defines the dimensions and color 
bltma D information for a Windows 3.0 device-independent bitmap. 

information 



typedef struct tagBITMAPINFO { 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColorsfl]; 

} BITMAPINFO; 



TBitmapInfo = record 

bmiHeader: TBitmapInfoHeader; 

bmiColors: array[0..0] of TRGBQuad; 
end; 



The BITMAPINFO structure contains the following fields: 
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BITMAPINFO 



Field Description 



bmiHeader Specifies a BITMAPINFOHEADER data structure that contains 

information about the dimensions and color format of a device- 
independent bitmap. 

bmiColors Specifies an array of RGBQUAD data structures that define the 

colors in the bitmap. 

Comments A Windows 3.0 device-independent bitmap consists of two distinct parts: 
a BITMAPINFO data structure that describes the dimensions and colors of 
the bitmap, and an array of bytes that define the pixels of the bitmap. The 
bits in the array are packed together, but each scan line must be zero- 
padded to end on a LONG boundary. Segment boundaries can appear 
anywhere in the bitmap, however. The origin of the bitmap is the lower- 
left corner. 

The biBitCount field of the BITMAPINFOHEADER structure determines 
the number of bits which define each pixel and the maximum number of 
colors in the bitmap. This field may be set to any of the following values: 

Value Description 

1 The bitmap is monochrome, and the bmiColors field must contain two 

entries. Each bit in the bitmap array represents a pixel. If the bit is 
clear, the pixel is displayed with the color of the first entry in the 
bmiColors table; if the bit is set, the pixel has the color of the second 
entry in the table. 

4 The bitmap has a maximum of 16 colors, and the bmiColors field 

contains up to 16 entries. Each pixel in the bitmap is represented by a 
four-bit index into the color table. For example, if the first byte in the 
bitmap is OxlF, then the byte represents two pixels. The first pixel 
contains the color in the second table entry, and the second pixel 
contains the color in the 16th table entry. 

8 The bitmap has a maximum of 256 colors, and the bmiColors field 

contains up to 256 entries. In this case, each byte in the array 
represents a single pixel. 

24 The bitmap has a maximum of 2 24 colors. The bmiColors field is 

NULL, and each three bytes in the bitmap array represents the relative 
intensities of red, green, and blue, respectively, of a pixel. 

The bICIrUsed field of the BITMAPINFOHEADER structure specifies the 
number of color indexes in the color table actually used by the bitmap. If 
the biClrllsed field is set to 0, the bitmap uses the maximum number of 
colors corresponding to the value of the biBitCount field. 

The colors in the bmiColors table should appear in order of importance. 

Alternatively, for functions that use device-independent bitmaps, the 
bmiColors field can be an array of 16-bit unsigned integers that specify an 
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index into the currently realized logical palette instead of explicit RGB 
values. In this case, an application using the bitmap must call device- 
independent bitmap functions with the wllsage parameter set to 
DIB_PAL_COLORS. 

The bmiColors field should not contain palette indices if the bitmap is to 
be stored in a file or transferred to another application. Unless the 
application uses the bitmap exclusively and under its complete control, 
the bitmap color table should contain explicit RGB values. 



BITMAPINFOHEADER 



3.0 











Device- 








independent 


The BITMAPINFOHEADER structure contains information about the 


bitmap 


dimensions and color format of a Windows 3.0 device-independent 


format 


bitmap. 






information 










typedef struct tagBITMAPINFOHEADER{ 


TBitmapInfoHeader = record 




DWORD 


biSize; 


biSize: Longint; 




DWORD 


biWidth; 


biWidth: Longint; 




DWORD 


biHeight; 


biHeight: Longint; 




WORD 


biplanes; 


biPlanes: Word; 




WORD 


biBitCount 


biBitCount: Word; 




DWORD 


biCompression; 


biCompression: Longint; 




DWORD 


biSizelmage; 


biSizelmage: Longint; 




DWORD 


biXPelsPerMeter; 


biXPelsPerMeter: Longint; 




DWORD 


biYPelsPerMeter; 


biYPelsPerMeter: Longint; 




DWORD 


biClrUsed; 


biClrUsed: Longint; 




DWORD 


biClrlmportant; 


biClrlmportant: Longint; 




} BITMAPINFOHEADER; 


end; 




The BITMAPINFOHEADER structure has the following fields: 




Field 


Description 





biSize Specifies the number of bytes required by the BITMAP- 

INFOHEADER structure. 

biWidth Specifies the width of the bitmap in pixels. 

biHeight Specifies the height of the bitmap in pixels. 

biPlanes Specifies the number of planes for the target device and must 

be set to 1. 

biBitCount Specifies the number of bits per pixel. This value must be 1, 4, 

8, or 24. 
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biCompression Specifies the type of compression for a compressed bitmap. It 

can be one of the following values:. 

Value Description 

BI_RGB Specifies that the bitmap is not compressed. 

BI_RLE8 Specifies a run-length encoded format for 

bitmaps with 8 bits per pixel. The compression 
format is a two-byte format consisting of a 
count byte followed by a byte containing a 
color index. See the following "Comments" 
section for more information. 

BI_RLE4 Specifies a run-length encoded format for 

bitmaps with 4 bits per pixel. The compression 
format is a two-byte format consisting of a 
count byte followed by two word-length color 
indexes. See the following "Comments" 
section for more information. 



biSizelmage 
biXPelsPerMeter 



biYPelsPerMeter 
biClrUsed 



Comments 



Specifies the size in bytes of the image. 
Specifies the horizontal resolution in pixels per meter of the 
target device for the bitmap. An application can use this 
value to select a bitmap from a resource group that best 
matches the characteristics of the current device. 
Specifies the vertical resolution in pixels per meter of the 
target device for the bitmap. 

Specifies the number of color indexes in the color table 
actually used by the bitmap. If this value is 0, the bitmap uses 
the maximum number of colors corresponding to the value of 
the biBitCount field. See the description of the BITMAPINFO 
data structure earlier in this chapter for more information on 
the maximum sizes of the color table. If biClrUsed is nonzero, 
then the biClrUsed field specifies the actual number of colors 
which the graphics engine or device driver will access if the 
biBitCount field is less than 24. If the biBitCount field is set to 
24, the biClrUsed field specifies the size of the reference color 
table used to optimize performance of Windows color 
palettes. If the bitmap is a "packed" bitmap (that is, a bitmap 
in which the bitmap array immediately follows the 
BITMAPFINO header and which is referenced by a single 
pointer), the biClrUsed field must be set to or to the actual 
size of the color table. 

Specifies the number of color indexes that are considered 
important for displaying the bitmap. If this value is 0, then all 
colors are important. 

The BITMAPINFO data structure combines the BITMAPINFOHEADER 

structure and a color table to provide a complete definition of the 
dimensions and colors of a Windows 3.0 device-independent bitmap. See 
the description of the BITMAPINFO data structure for more information 
about specifying a Windows 3.0 device-independent bitmap. 



biClrlmportant 
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An application should use the information stored in the biSize field to 
locate the color table in a BITMAPINFO data structure with a method such 
as the following: 

pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo -» biSize) ) 

Bitmap compression formats 

Windows supports formats for compressing bitmaps that define their 
colors with 8 bits per pixel and with 4 bits per pixel. Compression reduces 
the disk and memory storage required for the bitmap. The following 
paragraphs describe these formats. 

When the biCompression field is set to BIJRLE8, the bitmap is 
compressed using a run-length encoding format for an 8-bit bitmap. This 
format may be compressed in either of two modes: 

m Encoded 
□ Absolute 

Both modes can occur anywhere throughout a single bitmap. 

Encoded mode consists of two bytes: the first byte specifies the number of 
consecutive pixels to be drawn using the color index contained in the 
second byte. In addition, the first byte of the pair can be set to zero to 
indicate an escape that denotes an end of line, end of bitmap, or a delta. 
The interpretation of the escape depends on the value of the second byte 
of the pair. The following list shows the meaning of the second byte: 

Second Byte 

Of Escape Meaning 

End of line. 

1 End of bitmap. 

2 Delta. The two bytes following the escape contain unsigned 
values indicating the horizontal and vertical offset of the next 
pixel from the current position. 

Absolute mode is signalled by the first byte set to zero and the second 
byte set to a value between 03H and FFH. In absolute mode, the second 
byte represents the number of bytes which follow, each of which contains 
the color index of a single pixel. When the second byte is set to 2 or less, 
the escape has the same meaning as in encoded mode. In absolute mode, 
each run must be aligned on a word boundary. 

The following example shows the hexadecimal values of an 8-bit 
compressed bitmap: 

03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01 
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02 78 00 00 09 IE 00 01 

This bitmap would expand as follows (two-digit values represent a color 
index for a single pixel): 

04 04 04 

06 06 06 06 06 
45 56 67 

78 78 

move current position 5 right and 1 down 

78 78 

end of line 

IE IE IE IE IE IE IE IE IE 

end of RLE bitmap 

When the biCompression field is set to BIJRLE4, the bitmap is 
compressed using a run-length encoding format for a 4-bit bitmap, which 
also uses encoded and absolute modes. In encoded mode, the first byte of 
the pair contains the number of pixels to be drawn using the color indexes 
in the second byte. The second byte contains two color indexes, one in its 
high-order nibble (that is, its low-order four bits) and one in its low-order 
nibble. The first of the pixels is drawn using the color specified by the 
high-order nibble, the second is drawn using the color in the low-order 
nibble, the third is drawn with the color in the high-order nibble, and so 
on, until all the pixels specified by the first byte have been drawn. 

In absolute mode, the first byte contains zero, the second byte contains the 
number of color indexes that follow, and subsequent bytes contain color 
indexes in their high- and low-order nibbles, one color index for each 
pixel. In absolute mode, each run must be aligned on a word boundary. 
The end-of-line, end-of-bitmap, and delta escapes also apply to BI_RLE4. 

The following example shows the hexadecimal values of a 4-bit 
compressed bitmap: 

03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01 

04 78 00 00 09 IE 00 01 

This bitmap would expand as follows (single-digit values represent a 
color index for a single pixel): 

4 

6 6 

4 5 5 6 6 7 

7 8 7 8 

move current position 5 right and 1 down 
7 8 7 8 
end of line 

1 E 1 E 1 E 1 E 1 
end of RLE bitmap 
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CUENTCREATESTRUCT 



3.0 



MDI client 

window 

creation 

structure 



The CLIENTCREATESTRUCT data structure contains information about 
the menu and first multiple document interface (MDI) child window of an 
MDI client window. An application passes a long pointer to this structure 
as the IpParam parameter of the CreateWindow function when creating an 
MDI client window. 



typedef struct tagCLIENTCREATESTRUCT 
{ 

HMENU hWindowMenu; 

WORD idFirstChild; 
} CLIENTCREATESTRUCT; 



TClientCreateStruct = record 
hWindowMenu: THandle; 
idFirstChild: Word; 

end; 



The CLIENTCREATESTRUCT structure contains the following fields: 

Field Description 

hWindowMenu Is the menu handle of the application's Window menu. An 

application can retrieve this handle from the MDI frame 
window's menu using the GetSubMenu function. 

idFirstChild Is the child window ID of the first MDI child window 

created. Windows increments the ID for each additional MDI 
child window that the application creates, and reassigns 
identifiers when the application destroys a window to keep 
the range of identifiers continuous. These identifiers are used 
in WM_COMMAND messages to the application's MDI 
frame window when a child window is selected from the 
Window menu, and should not conflict with any other 
command identifiers. 



COLORREF 



Color 
specification 



A COLORREF color value is a long integer that specifies a color. GDI 
functions that require a color (such as CreatePen and FloodFill) accept a 
COLORREF value as a parameter. Depending on how an application uses 
the COLORREF value, the value has three distinct forms. It may specify 
any of the following: 



i Explicit values for red, green, and blue (RGB) 
i An index into a logical color palette 
i A palette-relative RGB value 
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TColorRef = Longint; 

Explict RGB When specifying an explicit RGB value, the COLORREF value has the 
following hexadecimal form: 

OxOObbggrr 

The low-order byte contains a value for the relative intensity of red; the 
second byte contains a value for green, and the third byte contains a value 
for blue. The high-order byte must be zero. The maximum value for a 
single byte is FF (hexadecimal). The following list illustrates the 
hexadecimal values that produce the indicated colors. 



Value 



Color 



OxOOOOOOFF 


Pure red 


OxOOOOFFOO 


Pure green 


OxOOFFOOOO 


Pure blue 


0x00000000 


Black 


OxOOFFFFFF 


White 


0x00808080 


Medium gray 



The RGB macro accepts values for red, green, and blue, and returns an 
explicit RGB COLORREF value. 

Palette index When specifying an index into a logical color palette, the COLORREF 
value has the following hexadecimal form: 

OxOlOOiiii 

The two low-order bytes consist of a 16-bit integer specifying an index 
into a logical palette. The third byte is not used and must be zero. The 
fourth (high-order) byte must be set to 1. 

For example, the hexadecimal value 0x01000000 specifies the color in the 
palette entry of index 0; 0x0100000c specifies the color in the entry of 
index 12, and so on. 

The PALETTEINDEX macro accepts an integer representing an index into 
a logical palette and returns a palette-index COLORREF value. 

Palette- 

relative rgb When specifying a palette-relative RGB value, the COLORREF value has 
the following hexadecimal form: 

0x02bbggrr 

As with an explicit RGB, the three low-order bytes contain values for red, 
green, and blue; the high-order byte must be set to 2. 
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Comments 



For output devices that support logical palettes, Windows matches a 
palette-relative RGB value to the nearest color in the logical palette of the 
device context, as though the application had specified an index to that 
palette entry. If an output device does not support a system palette, then 
Windows uses the palette-relative RGB as though it were an explict RGB 
COLORREF value. 

The PALETTERGB macro accepts values for red, green, and blue, and 
returns a palette-relative RGB COLORREF value. 

Before passing a palette-index or palette-relative RGB COLORREF value 
to a function that also requires a device-context parameter, an application 
that uses its own palette must select its palette into the device context (by 
calling the SelectPalette function) and realize the palette (by calling 
RealizePalette). This ensures that the function will use the correct palette- 
entry color. For functions that create an object (such as CreatePen), the 
application must select and realize the palette before selecting the object 
for the device context. 



COMPAREITEMSTRUCT 



3.0 



Owner- 
draw item- 
sorting 
information 



The COMPAREITEMSTRUCT structure supplies the identifiers and 
application-supplied data for two items in a sorted owner-draw combo 
box or list box. 

Whenever an application adds a new item to an owner-draw combo or list 
box created with the CBS_SORT or LBS_SORT style, Windows sends the 
owner a WM_COMPAREITEM message. The IParam parameter of the 
message contains a long pointer to a COMPAREITEMSTRUCT data 
structure. When the owner receives the message, the owner compares the 
two items and returns a value indicating which item sorts before the other. 
For more information, see the description of the WM_COMPAREITEM 
message in Chapter 6, "Messages directory," in Reference, Volume 1 . 



typedef struct tagCOMPAREITEMSTRUCT { 



WORD 


CtlType; 


WORD 


CtllD; 


HWND 


hwndltera; 


WORD 


itemlDl; 


DWORD 


itemDatal; 


WORD 


itemID2; 


DWORD 


iteraData2; 


COMPAREITEMSTRUCT; 



TCompareltemStruct = record 

CtlType: Word; 

CtllD: Word; 

hwndltem: HWnd; 

itemlDl: Word; 

itemDatal: Longint; 

itemID2: Word; 

itemData2: Longint; 
end; 
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The COMPAREITEMSTRUCT structure has the following fields: 

Field Description 

CtlType Is ODT_LISTBOX (which specifies an owner-draw list box) or 

ODT_COMBOBOX (which specifies an owner-draw combo 
box). 

CtllD Is the control ID for the list box or combo box. 

hwndltem Is the window handle of the control. 

itemlDI Is the index of the first item in the list box or combo box being 

compared. 

itemDatal Is application-supplied data for the first item being 

compared. This value was passed as the IParam parameter of 
the message that added the item to the combo or list box. 

itemlD2 Is the index of the second item in the list box or combo box 

being compared. 

itemData2 Is application-supplied data for the second item being 

compared. This value was passed as the IParam parameter of 
the message that added the item to the combo or list box. 



COMSTAT 



Communi- 
cation 
device 
status 



The COMSTAT structure contains information about a communications 
device. 



typedef struct tagCOMSTAT 
BYTE fCtsHold: 1; 
BYTE fDsrHold: 1; 



BYTE fRlsdHold: 
BYTE fXoffHold: 
BYTE fXoffSent: 
BYTE fEof: 1; 
BYTE fTxim: 1; 
WORD cblnQue; 
WORD cbOutQue; 
COMSTAT; 



TComStat = record 
Flags: Byte; 
cblnQue: Word; 
cbOutQue: Word; 

end; 



The COMSTAT structure has the following fields: 



Field 



Description 



fCtsHold: 1 Specifies whether transmission is waiting for the clear- to- 

send (CTS) signal to be sent. 

fDsrHold: 1 Specifies whether transmission is waiting for the data-set- 

ready (DSR) signal to be sent. 

fRlsdHold: 1 Specifies whether transmission is waiting for the receive- 

line-signal-detect (RLSD) signal to be sent. 
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fXoffHold: 1 
fXoffSent: 1 



fEof: 1 
fTxim: 1 
cblnQue 
cbOutQue 



Specifies whether transmission is waiting as a result of the 

XoffChar character being received. 

Specifies whether transmission is waiting as a result of the 

XoffChar character being transmitted. Transmission halts 

when the XoffChar character is transmitted and used by 

systems that take the next character as XON, regardless of the 

actual character. 

Specifies whether the EofChar character has been received. 

Specifies whether a character is waiting to be transmitted. 

Specifies the number of characters in the receive queue. 

Specifies the number of characters in the transmit queue. 



See also The GetCommError function in Chapter 4, "Functions directory," in 
Reference, Volume 1. 



CREATESTRUCT 



Window- 

CrGOtiOn The CREATESTRUCT structure defines the initialization parameters 
Structure passed to an application's window function. 



■pedef struct tagCREATESTRUCT { 


TCreateStruct = record 


LPSTR 


lpCreateParams; 


lpCreateParams: PChar 


HANDLE 


hlnstance; 


hlnstance: THandle; 


HANDLE 


hMenu; 


hMenu: THandle; 


HWND 


hwndParent; 


hwndParent: HWnd; 


int 


cy; 


cy: Integer; 


int 


ex; 


ex: Integer; 


int 


y; 


y: Integer; 


int 


x; 


x: Integer; 


long 


style; 


style: Longlnt; 


LPSTR 


IpszName; 


IpszName: PChar; 


LPSTR 


IpszClass; 


IpszClass: PChar; 


long 


ExStyle; 


dwExStyle: Longint; 


CREATESTRUCT; 


end; 



The CREATESTRUCT structure has the following fields: 



Field 



Description 



lpCreateParams 
hlnstance 

hMenu 
hwndParent 

cy 



Points to data to be used for creating the window. 
Identifies the module-instance handle of the module that 
owns the new window. 

Identifies the menu to be used by the new window. 
Identifies the window that owns the new window. This field 
is NULL if the new window is a top-level window. 
Specifies the height of the new window. 
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ex 

y 



style 
IpszName 

IpszClass 

ExStyle 



Specifies the width of the new window. 

Specifies the y-coordinate of the upper-left corner of the new 

window. Coordinates are relative to the parent window if the 

new window is a child window. Otherwise, the coordinates 

are relative to the screen origin. 

Specifies the x-coordinate of the upper-left corner of the new 

window. Coordinates are relative to the parent window if the 

new window is a child window. Otherwise, the coordinates 

are relative to the screen origin. 

Specifies the new window's style. 

Points to a null-terminated character string that specifies the 

new window's name. 

Points to a null-terminated character string that specifies the 

new window's class name. 

Specifies extended style for the new window. 



DCB 



Communi- 
cations 
device 
control 
block 



The DCB structure defines the control setting for a se 


device. 






typedef 


struct tagDCB { 


TDCB = record 


BYTE 


Id; 


Id: Byte; 


WORD 


BaudRate; 


BaudRate: Word; 


BYTE 


ByteSize; 


ByteSize: Byte; 


BYTE 


Parity; 


Parity: Byte; 


BYTE 


StopBits; 


StopBits: Byte; 


WORD 


RlsTimeout; 


RlsTimeout: Word 


WORD 


CtsTimeout; 


CtsTimeout: Word 


WORD 


DsrTimeout; 


DsrTimeout: Word 
Flags: Word; 


BYTE 


f Binary: 1; 


XonChar: Char; 


BYTE 


fRtsDisable: 1; 


XoffChar: Char; 


BYTE 


f Parity: 1; 


XonLim: Word; 


BYTE 


fOutxCtsFlow: 1; 


XoffLim: Word; 


BYTE 


fOutxDsrFlow: 1; 


PeChar: Char; 


BYTE 


f Dummy : 2 ; 


EofChar: Char; 


BYTE 


fDtrDisable: 1; 


EvtChar: Char; 
TxDelay. Word; 


BYTE 


fOutX: 1; 


end; 


BYTE 


flnX: 1; 




BYTE 


fPeChar: 1; 




BYTE 


fNull: 1; 




BYTE 


fChEvt: 1; 




BYTE 


fDtrflow: 1; 




BYTE 


fRtsflow: 1; 
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BYTE fDummy2: 1; 

char XonChar; 
char XoffChar; 
WORD XonLim; 
WORD XoffLim; 
char PeChar; 
char EofChar; 
char EvtChar; 
WORD TxDelay; 
} DCB; 

The DCB structure has the following fields: 



Field 



Description 



Id 

BaudRate 

ByteSize 

Parity 



StopBits 



RIsTimeout 

CtsTimeout 
DsrTimeout 
fBinary: 1 

fRtsDisable: 1 



Specifies the communication device. This value is set by the 

device driver. If the most significant bit is set, then the DCB 

structure is for a parallel device. 

Specifies the baud rate at which the communications device 

operates. 

Specifies the number of bits in the characters transmitted and 

received. The ByteSize field can be any number from 4 to 8. 

Specifies the parity scheme to be used. The Parity field can be 

any one of the following values: 



Value 


Meaning 


EVENPARITY 


Even 


MARKPARITY 


Mark 


NOPARITY 


No parity 


ODDPARITY 


Odd 


SPACEPARITY 


Space 



Specifies the number of stop bits to be used. The StopBits 
field can be any one of the following values: 

Value Meaning 

ONESTOPBIT 1 stop bit 

ONE5STOPBITS 1 .5 stop bits 

TWOSTOPBITS 2 stop bits 

Specifies the maximum amount of time (in milliseconds) the 
device should wait for the receive-line-signal-detect (RLSD) 
signal. (RLSD is also known as the carrier detect (CD) signal.) 
Specifies the maximum amount of time (in milliseconds) the 
device should wait for the clear-to-send (CTS) signal. 
Specifies the maximum amount of time (in milliseconds) the 
device should wait for the data-set-ready (DSR) signal. 
Specifies binary mode. In nonbinary mode, the EofChar 
character is recognized on input and remembered as the end 
of data. 

Specifies whether or not the request-to-send (RTS) signal is 
disabled. If the fRtsDisable field is set, RTS is not used and 
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fParity: 1 
fOutxCtsFlow: 1 
fOutxDsrFlow: 1 



fDummy: 2 
fDtrDisable: 1 



fOutX: 1 



flnX: 1 



fPeChar: 1 



fNull: 1 
fChEvt: 1 

fDtrflow: 1 



fRtsflow: 1 



fdummy2: 1 
XonChar 

XoffChar 

XonLim 

XoffLim 



remains low. If f RtsDisable is clear, RTS is sent when the 

device is opened and turned off when the device is closed. 

Specifies whether parity checking is enabled. If the f Parity 

field is set, parity checking is performed and errors are 

reported. 

Specifies that clear-to-send (CTS) signal is to be monitored for 

output flow control. If the fOutxCtsFlow field is set and CTS 

is turned off, output is suspended until CTS is again sent. 

Specifies that the data-set-ready (DSR) signal is to be 

monitored for output flow control. If the fOutxDsrFlow field 

is set and DSR is turned off, output is suspended until DSR is 

again sent. 

Reserved. 

Specifies whether the data-terminal-ready (DTR) signal is 

disabled. If the fDtrDisable field is set, DTR is not used and 

remains low. If fDtrDisable is clear, DTR is sent when the 

device is opened and turned off when the device is closed. 

Specifies that XON/XOFF flow control is used during 

transmission. If the fOutX field is set, transmission stops 

when the XoffChar character is received, and starts again 

when the XonChar character is received. 

Specifies that XON/XOFF flow control is used during 

reception. If the flnX field is set, the XonChar character is sent 

when the receive queue comes within XoffLim characters of 

being full, and the XonChar character is sent when the 

receive queue comes within XonLim characters of being 

empty. 

Specifies that characters received with parity errors are to be 

replaced with the character specified by the fPeChar field. 

The f Parity field must be set for the replacement to occur. 

Specifies that received null characters are to be discarded. 

Specifies that reception of the EvtChar character is to be 

flagged as an event. 

Specifies that the data-terminal-ready (DTR) signal is to be 

used for receive flow control. If the fDtrflow field is set, DTR 

is turned off when the receive queue comes within XoffLim 

characters of being full, and sent when the receive queue 

comes within XonLim characters of being empty. 

Specifies that the ready-to-send (RTS) signal is to be used for 

receive flow control. If the fRtsflow field is set, RTS is turned 

off when the receive queue comes within XoffLim characters 

of being full, and sent when the receive queue comes within 

XonLim characters of being empty. 

Reserved. 

Specifies the value of the XON character for both 

transmission and reception. 

Specifies the value of the XOFF character for both 

transmission and reception. 

Specifies the minimum number of characters allowed in the 

receive queue before the XON character is sent. 

Specifies the maximum number of characters allowed in the 

receive queue before the XOFF character is sent. The XoffLim 
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PeChar 

EofChar 

EvtChar 
TxDelay 



value is subtracted from the size of the receive queue (in 

bytes) to calculate the maximum number of characters 

allowed. 

Specifies the value of the character used to replace characters 

received with a parity error. 

Specifies the value of the character used to signal the end of 

data. 

Specifies the value of the character used to signal an event. 

Not currently used. 



See also The BuildCommDCB, GetCommState, and SetCommState functions in 
Chapter 4, "Functions directory," in Reference, Volume 1. 



DELETEITEMSTRUCT 



3.0 



Deleted 
owner-draw 
list-box item 



The DELETEITEMSTRUCT structure describes a deleted owner-draw list- 
box or combo-box item. When an item is removed from the list box or 
combo box, or when the list box or combo box is destroyed, Windows 
sends the WM_DELETEITEM message to the owner for each deleted item; 
the IParam parameter of the message contains a pointer to this structure. 

TDeleteltemStruct = record 
CtlType: Word; 
CtlType CtllD: Word; 

CtllD; itemID: Word; 

itemID; hwndltem: HWnd; 

hwndltem; itemData: Longint; 

itemData; end '' 



typedef struct tagDELETEITEMSTRUCT 



WORD 

WORD 

WORD 

HWND 

DWORD 

DELETEITEMSTRUCT; 



The DELETEITEMSTRUCT structure has the following fields: 

Field Description 

CtlType Is ODT_LISTBOX (which specifies an owner-draw list box) or 

ODT_COMBOBOX (which specifies an owner-draw combo box). 

CtllD Is the control ID for the list box or combo box. 

itemID Is the index of the item in the list box or combo box being 

removed. 

hwndltem Is the window handle of the control. 

itemData Contains the value passed to the control in the IParam parameter 

of the LBJNSERTSTRING, LB_ADDSTRING, 
CBJNSERTSTRING, or CB_ADDSTRING message when the 
item was added to the list box. 
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DEVMODE 



3.0 



Printer driver 

initiOliZOtiOn The DEVMODE data structure contains information about the device 
informntion initialization and environment of a printer driver. An application passes 
this structure to the DeviceCapabilities and ExtDeviceMode functions. 



of Char; 



typedef struct devicemode { 


TDevMode = record 


char 


dmDeviceName[32] ; 


dmDeviceName: 


WORD 


dmSpecVersion; 


array [ 0. .cchDeviceName-1] o 


WORD 


dmDriverVersion; 


dmSpecVersion: Word; 


WORD 


dmSize; 


dmDriverVersion: Word; 


WORD 


dmDriverExtra; 


dmSize: Word; 


DWORD 


dmFields; 


dmDriverExtra: Word; 


short 


dmOrientation; 


dmFields: Longlnt; 


short 


dmPaperSize; 


dmOrientation: Integer; 


short 


dmPaperLength; 


dmPaperSize: Integer; 


short 


dmPaperWidth; 


dmPaperLength: Integer; 


short 


dmScale; 


dmPaperWidth: Integer; 


short 


dmCopies; 


dmScale: Integer; 


short 


dmDefaultSource; 


dmCopies: Integer; 


short 


dmPrintQuality; 


dmDefaultSource: Integer; 


short 


dmColor; 


dmPrintQuality: Integer; 


short 


dmDuplex; 


dmColor: Integer; 


BYTE 




dmDuplex: Integer; 


dmDriverData[dmDriverExtra] ; 


end; 


} DEVMODE; 





The DEVMODE structure contains the following fields: 



Field 



Description 



dmDeviceName 
dmSpecVersion 

dmDriverVersion 
dmSize 



Specifies the name of the device the driver supports; for 
example, "PCL/HP LaserJet" in the case of PCL/HP® 
LaserJet®. This string is unique among device drivers. 
Specifies the version number of the initialization data 
specification upon which the structure is based. The 
version number follows the Windows version number and 
is currently 0x300. 

Specifies the printer driver version number assigned by 
the printer driver developer. 

Specifies the size in bytes of the DEVMODE structure 
except the dmDriverData (device-specific) field. If an 
application manipulates only the driver-independent 
portion of the data, it can use this field to determine the 
length of the structure without having to account for 
different versions. 
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dmDriverExtra 



dmFields 



dmOrientation 



dmPaperSize 



dmPaperLength 



dmPaperWidth 
dmScale 



dmCopies 
dmDefaultSource 



Contains the size of the dmDriverData field and is the 
length of the device-specific data in the DEVMODE 
structure. If an application does not use device-specific 
information, it should set this field to zero. 
Is a bitfield that specifies which of the remaining fields in 
the DEVMODE structure have been initialized. Bit 
(defined as DM_ORIENTATION) corresponds to 
dmOrientation; bit 1 (defined as DM_PAPERSIZE) 
specifies dmPaperSize, and so on. A printer driver 
supports only those fields that are appropriate for the 
printer technology. 

Selects the orientation of the paper. It can be either 
DMORIENT_PORTRAIT (1) or 
DMORIENT_LANDSCAPE (2). 

Selects the size of the paper to print on. This field may be 
set to zero if the length and width of the paper are both set 
by the dmPaperLength and dmPaperWidth fields. 
Otherwise, the dmPaperSize field can be set to one of the 
following predefined values: 

Value Meaning 

DMPAPER_LETTER 8/2-by-l 1-inch paper 

DMPAPER_LEGAL 8/2-by-14-inch paper 

DMPAPER_A4 210-by-297-millimeter paper 

DMPAPER_CSHEET 17-by-22-inch paper 

DMPAPER_DSHEET 22-by-34-inch paper 

DMPAPER_ESHEET 34-by-44-inch paper 

DMPAPER_ENV_9 3 /8-by-8/8-inch #9 envelope 

DMPAPER_ENV_10 4 /8-by-9/ 5-inch #10 envelope 

DMPAPER_ENV_11 4/2-by-10/8-inch#ll envelope 

DMPAPER_ENV_12 4/4-by-l 1-inch #12 envelope 

DMPAPER_ENV_14 5-by-l 1 /2-inch #14 envelope 

Overrides the length of the paper specified by the 

dmPaperSize field, either for custom paper sizes or for 

devices such as dot-matrix printers which can print on a 

page of arbitrary length. These values, along with all other 

values which specify a physical length, are in tenths of a 

millimeter. 

Overrides the width of the paper specified by the 

dmPaperSize field. 

Scales the printed output. The apparent page size is scaled 

by a factor of dmScale/100 from the physical page size. A 

letter-size paper with a dmScale value of 50 would appear 

to be 17 by 22 inches, and output text and graphics would 

be correspondingly half their normal height and width. 

Selects the number of copies printed if the device supports 

multiple-page copies. 

Specifies the paper bin from which the paper is fed by 

default. The application can override this selection by 

using the GETSETPAPERBINS escape. Possible bins 

include the following: 
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n DMBIN_DEFAULT 

□ DMBIN_UPPER 
n DMBIN_LOWER 

a DMBIN_MANUAL 

□ DMBIN_TRACTOR 

n DMBIN_ENVELOPE 

There is also a range of values reserved for device-specific 
bins. The GETSETPAPERBINS and ENUMPAPERBINS 
escapes use these indexes to be consistent with 
initialization information. 
dmPrintQuality Specifies the printer resolution. There are four predefined 

device-independent values: 

D DMRES_HIGH (-4) 

a DMRES_MEDIUM (-3) 

p DMRES_LOW (-2) 

□ DMRES_DRAFT (-1) 

If a positive value is given, it specifies the number of dots 
per inch (DPI) and is therefore device dependent. 
Switches between color and monochrome on color 
printers. Possible values are: 

D DMCOLOR_COLOR (1) 

□ DMCOLOR_MONOCHROME (2). 

Selects duplex or double-sided printing for printers 
capable of duplex printing. Values for this field include: 

n DMDUP_SIMPLEX Q) 

□ DMDUP_HORIZONTAL (2) 
p DMDUP_VERTICAL (3). 

dmDriverData[ ] Contains device-specific data defined by the device driver. 



dmColor 



dmDuplex 



Comments Only drivers fully updated for Windows version 3.0 and which export the 
ExtDeviceMode function use the DEVMODE data structure. 
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DLGTEMPLATE 



Dialog 
template 



The DLGTEMPLATE defines the contents of a dialog box. This structure is 
divided into three distinct parts: 

Part Description 



Header Data 
Structure 
Font-Information 
Data Structure 
List of Items 



Contains a general description of the dialog box. 

Defines the font with which text is drawn in the 

dialog box. This part is optional. 

Describes the parts that compose the dialog box. 



The CreateDialoglndirect, CreateDialoglndirectParam, DialogBoxIndirect, 
and DialogBoxIndirectParam functions use this structure. 



Header 

data The DLGTEMPLATE header is shown here: 

structure 



■pedef struct { 


long 


dtStyle; 


BYTE 


dtltemCount; 


int 


dtX; 


int 


dtY; 


int 


dtCX; 


int 


dtCY; 


char 


dtMenuName [ ] ; 


char 


dtClassName[] 


char 


dtCaptionText 


DLGTEMPLATE; 



The DLGTEMPLATE header has the following fields: 



Field 



Description 



dtStyle 



Specifies the style of the dialog box. This field may be any or 
all of these values: 



Value 

DS LOCALEDIT 



Meaning 

Specifies that text storage for edit 
controls will be allocated in the 
application's local data segment. 
This allows the use of the 
EM_GETHANDLE and 
EM_SETHANDLE messages. If 
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dtltemCount 
dtX 



dtY 

dtCX 
dtCY 



DS SYSMODAL 



DS ABSALIGN 



DS SETFONT 



this style is not specified, edit- 
control data is located in a 
separate global data block. 
Specifies a system-modal dialog 
box. 
DS_MODALFRAME Specifies a dialog box with a 

modal dialog-box border. This 
style can be combined with the 
WS_CAPTION and 
WS_SYSMENU style flags to 
create a dialog box with a title bar 
and System menu. 
Indicates that dtX and dtY are 
relative to the screen origin, not to 
the owner of the dialog box. 
Specifies that a font other than the 
system font is to be used to draw 
text in the dialog box. If this flag is 
set, the FONTINFO data structure 
described in the following 
paragraphs must immediately 
follow the DLGTEMPLATE header. 
When Windows creates a dialog 
box with this attribute, Windows 
sends the WM_SETFONT 
message to the dialog-box 
window prior to creating the 
controls. 

Specifies that Windows will not 
send the WM_ENTERIDLE 
message to the owner of the 
dialog box while the dialog box is 
displayed. 
Specifies the number of items in the dialog box. A dialog box 
can contain up to 255 controls. 

Specifies the x-coordinate of the upper-left corner of the 
dialog box in units of /4 of the current dialog base width 
unit. The dialog base units are computed from the height and 
width of the current system font; the GetDialogBaseUnits 
function returns the current dialog base units in pixels. 
Unless DS_ABSALIGN is set in the dtStyle field, this value is 
relative to the origin of the parent window's client area. 
Specifies the y-coordinate of the upper-left corner of the 
dialog box in units of /8 of the current dialog base height 
unit. Unless DS_ABSALIGN is set in the dtStyle field, this 
value is relative to the origin of the parent window's client 
area. 

Specifies the width of the dialog box in units of /4 of the 
dialog base width unit. 

Specifies the height of the dialog box in units of / 8 of the 
dialog base height unit. 



DS NOIDLEMSG 
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dtMenuNamef ] Specifies a null-terminated string that specifies the name of 

the dialog box's menu. If this field is NULL, the dialog-box 
window does not have a menu. 

dtClassNamef ] Specifies a null-terminated string that supplies the name of 

the dialog box's class. If dtClassName[ ] is zero, it creates a 
dialog box with the standard dialog-box style. If an 
application specifies a class name, it should provide a dialog 
procedure that processes each dialog-box message directly or 
calls the DefDIgProc function to process the message. Also, 
the application must register the class with the cbWndExtra 
field of the WNDCLASS data structure set to 
DLGWINDOWEXTRA. 

dtCaptionTextf ] Specifies a null-terminated string that supplies the caption for 
the dialog box. 



Font- 
information 
data 
structure 



The FONTINFO data structure contains information about the point size 
and face name of the font which Windows is to use to draw text in the 
dialog box. 

typedef struct { 

short int PointSize; 

char szTypeFace[] ; /* A null-terminated string */ 
} FONTINFO; 

The FONTINFO structure has the following fields: 



Field 



Description 



PointSize Specifies the size of the typeface in points. 

szTypeFace Specifies the name of the typeface; for example, "Courier". 



Comments 



Item list 



The font specified must have been previously loaded, either from 
WIN.INI or explicitly by calling the LoadFont function. 

The item list consists of one or more DLGITEMTEMPLATE data structures, 
one for each control in the dialog box. The first such structure 
immediately follows the FONTINFO structure or the header at the first 
byte after the terminating null character in the szTypeFace field or the 
dtCaptionTextf ] field. The following shows the format of the 
DLGITEMTEMPLATE structure. 



typedef 


struct { 


int 


dtilX; 


int 


dtilY; 


int 


dtilCX; 


int 


dtilCY; 


int 


dtillD; 
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long 


dtilStyle; 


char 


dtilClassf 


char 


dtilText[] 


BYTE 


dtillnfo; 


PTR 


dtilData; 


DLGITEMTEMPLATE 



The DLGITEMTEMPLATE data structure has the following fields: 



Field 



Description 



dtilX 



dtilY 



dtilCX 



dtilCY 

dtillD 
dtilStyle 
dtilClass[ ] 



dtilText[ ] 
dtillnfo 

dtilData 



Specifies the x-coordinate of the upper-left corner of the dialog- 
box item in units of /4 of the current dialog base width unit, 
relative to the origin of the dialog box. The dialog base units are 
computed from the height and width of the current system font. 
The GetDialogBaseUnits function returns the current dialog base 
units in pixels. 

Specifies the y-coordinate of the upper-left corner of the dialog- 
box item in units of /8 of the current dialog base height unit. This 
value is relative to the origin of the dialog box. 
Specifies the width-extent of the dialog-box item in units of /4 of 
the current dialog base width unit. Dialog base units are 
computed from the height and width of the current system font. 
The GetDialogBaseUnits function returns the current dialog base 
units. 

Specifies the height of the dialog-box item in units of / 8 of the 
dialog base height unit. 

Specifies the dialog-box item identification number. 
Specifies the style of the dialog-box item. 

A null-terminated string that specifies the control's class. It may 
be one of the following class names: 

□ BUTTON 
nEDIT 

□ STATIC 

□ LISTBOX 

a SCROLLBAR 

□ COMBOBOX 

Specifies the text for the item; it is a null-terminated string. 
Specifies the number of bytes of additional data that follows this 
item description and precedes the next item description. 
Specifies additional data which the CreateWindow function 
receives through the IpCreateParams field of the 
CREATESTRUCT data structure. This field is zero length if dtillnfo 
is zero. 
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DRAWITEMSTRUCT 



3.0 



Owner- 
draw 
control 
drawing 
information 



The DRAWITEMSTRUCT structure provides information the owner needs 
to determine how to paint an owner-draw control. The owner of the 
owner-draw control receives a pointer to this structure as the IParam 
parameter of the WM_DRAWITEM message. 



typedef struct tagDRAWITEMSTRUCT 



WORD 


CtlType; 


WORD 


CtllD; 


WORD 


itemID; 


WORD 


itemAction; 


WORD 


itemState; 


HWND 


hwndltem; 


HDC 


hDC; 


RECT 


rcltem; 


DWORD 


itemData; 


DRAWITEMSTRUCT; 



TDrawItemStruct = record 

CtlType: Word; 

CtllD: Word; 

itemID: Word; 

itemAction: Word; 

itemState: Word; 

hwndltem: HWnd; 

hDC: HDC; 

rcltem: TRect; 

itemData: Longint; 
end; 



The DRAWITEMSTRUCT structure has the following fields: 



Field 



Description 



CtlType 



CtllD 
itemID 



itemAction 



Is the control type. The values for control types are as follows: 

Meaning 

Owner-draw button. 
Owner-draw combo 
box. 

Owner-draw list box. 
Owner-draw menu. 



Value 

ODT_BUTTON 
ODT_COMBOBOX 

ODT_LISTBOX 
ODT MENU 



Is the control ID for a combo box, list box or button. This field is 
not used for a menu. 

Is the menu-item ID for a menu or the index of the item in a list 
box or combo box. For an empty list box or combo box, this field 
can be -1. This allows the application to draw only the focus 
rectangle at the coordinates specified by the rcltem field even 
though there are no items in the control. This indicates to the 
user whether the list box or combo box has input focus. The 
setting of the bits in the itemAction field determines whether the 
rectangle is to be drawn as though the list box or combo box has 
input focus. 

Defines the drawing action required. This will be one or more of 
the following bits: 
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itemState 



hwndltem 

hDC 
rcltem 



itemData 



Value Description 

ODA_DRAWENTIRE This bit is set when the entire control 
needs to be drawn. 

ODA_FOCUS This bit is set when the control gains or 

loses input focus. The itemState field 
should be checked to determine 
whether the control has focus. 

ODA_SELECT This bit is set when only the selection 

status has changed. The itemState field 
should be checked to determine the new 
selection state. 

Specifies the visual state of the item after the current drawing 
action takes place. That is, if a menu item is to be grayed, the 
state flag ODS_GRAYED will be set. The state flags are: 



Value 

ODS_CHECKED 

ODS_DISABLED 

ODS_FOCUS 
ODS_GRAYED 

ODS SELECTED 



Description 

This bit is set if the menu item is to be 
checked. This bit is used only in a menu. 
This bit is set if the item is to be drawn 
as disabled. 

This bit is set if the item has input focus. 
This bit is set if the item is to be grayed. 
This bit is used only in a menu. 
This bit is set if the item's status is 
selected. 



For combo boxes, list boxes and buttons, this field specifies the 

window handle of the control; for menus, it contains the handle 

of the menu (HMENU) containing the item. 

Identifies a device context; this device context must be used 

when performing drawing operations on the control. 

Is a rectangle in the device context specified by the hDC field 

that defines the boundaries of the control to be drawn. Windows 

automatically clips anything the owner draws in the device 

context for combo boxes, list boxes, and buttons, but does not 

clip menu items. When drawing menu items, the owner must 

ensure that the owner does not draw outside the boundaries of 

the rectangle defined by the rcltem field. 

For a combo box or list box, this field contains the value that was 

passed to the list box in the IParatn parameter of one of the the 

following messages: 

a CB_ADDSTRING 
a CBJNSERTSTRING 
a LB_ADDSTRING 
D LBJNSERTSTRING 

For a menu, this field contains the DWORD value passed as the 
IpNezvItem parameter of the InsertMenu which inserted the menu 
item. Its contents are undefined for buttons. 
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HANDLETABLE 



Window- 

hondlG The HANDLETABLE structure is an array of handles, each of which 
tdblP identifies a GDI object. 



HANDLE objectHandle[l] 



THandleTable = record 

objectHandle: array[0..0] of 
THandle; 
end; 



The HANDLETABLE structure has the following field: 



Field 



Description 



objectHandle[1] Identifies an array of handles. 



LOGBRUSH 



Logical- 
brush The LOGBRUSH structure defines the style, color, and pattern of a 
attribute physical brush to be created by using the CreateBrushlndirect function. 

information 



typedef struct tagLOGBRUSH 
WORD lbStyle; 
COLORREF lbColor; 
short int lbHatch; 

} LOGBRUSH; 



TLogBrush = record 
lbStyle: Word; 
lbColor: Longint; 
lbHatch: Integer; 

end; 



The LOGBRUSH structure has the following fields: 



Field Description 



lbStyle Specifies the brush style. The lbStyle field can be any one of the 

following styles: 



Style 

BS DIBPATTERN 



BSJHATCHED 
BS HOLLOW 



Meaning 

Specifies a pattern brush defined by a 

device-independent bitmap (DIB) 

specification. 

Specifies a hatched brush. 

Specifies a hollow brush. 
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BS_PATTERN Specifies a pattern brush defined by a 

memory bitmap. 
BS_SOLID Specifies a solid brush. 

Specifies the color in which the brush is to be drawn. If IbStyle is 
BS_HOLLOW or BS_PATTERN / IbColor is ignored. If IpStyle is 
BSJDIBPATTERN, the low-order word of IbColor specifies whether 
the bmiColors fields of the BITMAPINFO data structure contain 
explicit RGB values or indexes into the currently realized logical 
palette. The IbColor field must be one of the following values: 

Value 

DIB PAL COLORS 



DIB RGB COLORS 



Meaning 

The color table consists of an array of 16-bit 

indexes into the currently realized logical 

palette. 

The color table contains literal RGB values. 



Specifies a hatch style. The meaning depends on the brush style. If 
IbStyle is BS_DIBPATTERN, the IbHatch field contains a handle to 
a packed DIB. To obtain this handle, an application calls the 
GlobalAlloc function to allocate a block of global memory and then 
fills the memory with the packed DIB. A packed DIB consists of a 
BITMAPINFO data structure immediately followed by the array of 
bytes which define the pixels of the bitmap. If IbStyle is 
BSJiATCHED, the IbHatch field specifies the orientation of the 
lines used to create the hatch. It can be any one of the following 
values: 



Value 

HS_BDIAGONAL 

HS_CROSS 

HS_DIAGCROSS 

HS_FDIAGONAL 

HS_HORIZONTAL 

HS VERTICAL 



Meaning 

45-degree upward hatch (left to right) 

Horizontal and vertical Crosshatch 

45-degree Crosshatch 

45-degree downward hatch (left to right) 

Horizontal hatch 

Vertical hatch 



If IbStyle is BS_PATTERN, IbHatch must be a handle to the bitmap 

that defines the pattern. 

If IbStyle is BS_SOLID or BS_HOLLOW, IbHatch is ignored. 

See also The CreateBrushlndirect function in Chapter 4, "Functions directory," in 
Reference, Volume 1 . 
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LOGFONT 



Logical-font 

dOSCfiptor The LOGFONT structure defines the attributes of a font, a drawing object 
used to write text on a display surface. 



typedef struct tagLOGFONT { 


TLogFont = record 




short int 


lfHeight; 


lfHeight: Integer; 




short int 


lfWidth; 


If Width: Integer; 




short int 


If Escapement; 


lfEscapement: Integer; 




short int 


lfOrientation; 


lfOrientation: Integer; 




short int 


1 f Weight; 


If Weight: Integer; 




BYTE 


lfltalic; 


lfltalic: Byte; 




BYTE 


lfUnderline; 


lfUnderline: Byte; 




BYTE 


If StrikeOut; 


If StrikeOut: Byte; 




BYTE 


lfCharSet; 


lfCharSet: Byte; 




BYTE 


lfOutPrecision; 


lfOutPrecision: Byte; 




BYTE 


lfClipPrecision; 


lfClipPrecision: Byte; 




BYTE 


lfQuality; 


lfQuality: Byte; 




BYTE 


lfPitchAndFamily; 


lfPitchAndFamily: Byte; 




BYTE 


IfFaceName [LF_FACESIZE] ; 


IfFaceName: array [0.. If 


FaceSize - 


} LOGFONT; 




1] of Byte; 
end; 




The LOGFONT structure has the following fields: 




Field 


Description 







lfHeight 



lfWidth 



lfEscapement 



Specifies the average height of the font (in user units). The 
height of a font can be specified in the following three ways. 
If the lfHeight field is greater than zero, it is transformed 
into device units and matched against the cell height of the 
available fonts. If lfHeight is zero, a reasonable default size 
is used. If lfHeight is less than zero, it is transformed into 
device units and the absolute value is matched against the 
character height of the available fonts. To ensure 
compatibility with the font-scaling engine of future versions 
of Windows, lfHeight should be less than zero. Setting the 
high-order bit indicates that the font height does not take 
internal leading into consideration. This corresponds to the 
standard typographical EM height. 
Specifies the average width of characters in the font (in 
device units). If the lfWidth field is zero, the aspect ratio of 
the device is matched against the digitization aspect ratio of 
the available fonts for the closest match by absolute value of 
the difference. 

Specifies the angle (in tenths of degrees) between the 
escapement vector and the x-axis of the display surface. The 
escapement vector is the line through the origins of the first 
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IfOrientation 



IfWeight 



Ifltalic 
IfUnderline 
IfStrikeOut 
IfCharSet 



IfOutPrecision 

IfClipPrecision 
IfQuality 



and last characters on a line. The angle is measured 

counterclockwise from the x-axis. 

Specifies the angle (in tenths of degrees) between the 

baseline of a character and the x-axis. The angle is measured 

counterclockwise from the x-axis. 

Specifies the font weight (in inked pixels per 1000). 

Although the IfWeight field can be any integer value from 

to 1000, the common values are as follows: 



Q400 
P700 



Normal 
Bold 



These values are approximate; the actual appearance 

depends on the font face. If IfWeight is zero, a default 

weight is used. 

Specifies an italic font if set to nonzero. 

Specifies an underlined font if set to nonzero. 

Specifies a strikeout font if set to nonzero. 

Specifies the font's character set. The three values are 

predefined: 

n ANSI_CHARSET 

□ OEM_CHARSET 

□ SYMBOL_CHARSET 

The OEM character set is system-dependent. Fonts with 
other character sets may exist in the system. If an 
application uses a font with an unknown character set, it 
should not attempt to translate or interpret strings that are 
to be rendered with that font. Instead, the strings should be 
passed directly to the output device driver. 
Specifies the font's output precision, which defines how 
closely the output must match the requested font's height, 
width, character orientation, escapement, and pitch. The 
default setting is OUT_DEFAULT_PRECIS. 
Specifies the font's clipping precision, which defines how to 
clip characters that are partially outside the clipping region. 
The default setting is CLIP_DEFAULT_PRECIS. 
Specifies the font's output quality, which defines how 
carefully GDI must attempt to match the logical- font 
attributes to those of an actual physical font. It can be any 
one of the following values: 

Value 

DEFAULT_QUALITY 



DRAFT_QUALITY 



Meaning 

Appearance of the font does not 
matter. 

Appearance of the font is less 
important than when 
PROOF_QUALITY is used. For GDI 
fonts, scaling is enabled, which 
means that more font sizes are 
available, but the quality may be 
lower. Bold, italic, underline, and 
strikeout fonts are synthesized if 
necessary. 
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IfPitchAndFamily 



PROOF_QUALITY Character quality of the font is 
more important than exact 
matching of the logical-font 
attributes. For GDI fonts, scaling is 
disabled and the font closest in size 
is chosen. Although the chosen font 
size may not be mapped exactly 
when PROOF_QUALITY is used, 
the quality of the font is high and 
there is no distortion of appearance. 
Bold, italic, underline, and strikeout 
fonts are synthesized if necessary. 

Specifies the font pitch and family. The two low-order bits 
specify the pitch of the font and can be any one of the 
following values: 

■ DEFAULT_PITCH 

■ FIXED_PITCH 

■ VARIABLE_PITCH 

The four high-order bits of the field specify the font family 
and can be any one of the following values: 

■ FF_DECORATIVE 

■ FF_DONTCARE 

■ FF_MODERN 

■ FF_ROMAN 

■ FF_SCRIPT 

■ FF_SWISS 

The proper value can be obtained by using the Boolean OR 
operator to join one pitch constant with one family constant. 
Font families describe the look of a font in a general way. 
They are intended for specifying fonts when the exact 
typeface desired is not available. The values for font 
families are as follows: 



Value 

FF_DECORATIVE 

FF_DONTCARE 
FF MODERN 



FF_ROMAN 

FF_SCRIPT 
FF SWISS 



Meaning 

Novelty fonts. Old English, for 

example. 

Don't care or don't know. 

Fonts with constant stroke width 

(fixed-pitch), with or without serifs. 

Fixed-pitch fonts are usually 

modern. Pica, Elite, and Courier, for 

example. 

Fonts with variable stroke width 

(proportionally spaced) and with 

serifs. Times Roman, Palatino, and 

Century Schoolbook, for example. 

Fonts designed to look like 

handwriting. Script and Cursive, 

for example. 

Fonts with variable stroke width 

(proportionally spaced) and 
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without serifs. Helvetica and Swiss, 
for example. 
If FaceName Specifies the font's typeface. It must be a null-terminated 

character string. If IfFaceName is NULL, GDI uses a default 

typeface. 

See also The CreateFontlndirect function in Chapter 4, "Functions directory," in 

Reference, Volume 1 . 



LOGPALETTE 



3.0 



Logical 

color 

palette 

information 



The LOGPALETTE data structure defines a logical color palette. 



typedef struct 



WORD palVersion; 

WORD palNumEntries; 

PALETTEENTRY palPalEntry [ ] ; 
} LOGPALETTE; 



TLogPalette = record 
palVersion: Word; 
palNumEntries: Word; 
palPalEntry: array [0 

TPaletteEntry; 

end; 



of 



The LOGPALETTE structure has the following fields: 

Field Description 

palVersion Specifies the Windows version number for the structure 

(currently 0x300). 
palNumEntries Specifies the number of palette color entries. 

palPalEntry [ ] Specifies an array of PALETTEENTRY data structures that 

define the color and usage of each entry in the logical 

palette. 

Comments The colors in the palette entry table should appear in order of importance. 
This is because entries earlier in the logical palette are most likely to be 
placed in the system palette. 

This data structure is passed as a parameter to the CreatePalette function. 
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LOGPEN 



Logical-pen 

attfibut© The LOGPEN structure defines the style, width, and color of a pen, a 
information drawing object used to draw lines and borders. The CreatePenlndirect 



function uses the LOGPEN structure. 

typedef struct tagLOGPEN { 

WORD lopnStyle; 

POINT lopnWidth; 

COLORREF lopnColor; 
} LOGPEN; 



TLogPen = record 
lopnStyle: Word; 
lopnWidth: TPoint; 
lopnColor: Longint; 

end; 



The LOGPEN structure has the following fields: 



Field 



Description 



lopnStyle 



Specifies the pen type, which can be any one of the following 
values: 

Result 



Constant Name 


Value 


PS SOLID 





PS DASH 


1 


PS DOT 


2 


PS DASHDOT 


3 


PS DASHDOTDOT 


4 


PS NULL 


5 


PS INSIDEFRAME 


6 



lopnWidth 
lopnColor 



If the width of the pen is greater than 1 and the pen style is 
PS_INSIDEFRAME, the line is drawn inside the frame of all 
primitives except polygons and polylines; the pen is drawn with a 
logical (dithered) color if the pen color does not match an available 
RGB value. The PSJNSIDEFRAME style is identical to PS_SOLID 
if the pen width is less than or equal to 1. 

Specifies the pen width (in logical units). If the lopnWidth field is 
zero, the pen is one pixel wide on raster devices. 

Specifies the pen color. 



Comments The y value in the POINT structure for lopnWidth is not used. 

See also The CreatePenlndirect function in Chapter 4, "Functions directory," in 
Reference, Volume 1 . 
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MDICREATESTRUCT 



3.0 



Mdi child 

window 

creation 

structure 



The MDICREATESTRUCT data structure contains information about the 
class, title, owner, location, and size of a multiple document interface 
(MDI) child window. 



typedef struct tagMDICREATESTRUCT 
{ 



LPSTR 


szClass; 


LPSTR 


szTitle; 


HANDLE 


hOwner; 


int 


x; 


int 


y; 


int 


ex; 


int 


cy; 


LONG 


style; 


LONG 


lParam; 


MDICREATESTRUCT; 



TMDICreateStruct = record 

szClass: PChar; 

szTitle: PChar; 

hOwner: THandle; 

x, y: Integer; 

ex, cy: Integer; 

style: Longlnt; 

lParam: Longlnt; 
end; 



The MDICREATESTRUCT structure contains the following fields: 



Field 



Description 



szClass 
szTitle 
hOwner 
x 



ex 
cy 
style 



Contains a long pointer to the application-defined class of the 

MDI child window. 

Contains a long pointer to the window title of the MDI child 

window. 

Is the instance handle of the application creating the MDI child 

window. 

Specifies the initial position of the left side of the MDI child 

window. If set to CWJJSEDEFAULT, the MDI child window is 

assigned a default horizontal position. 

Specifies the initial position of the top edge of the MDI child 

window. If set to CWJJSEDEFAULT, the MDI child window is 

assigned a default vertical position. 

Specifies the initial width of the MDI child window. If set to 

CWJJSEDEFAULT, the MDI child window is assigned a default 

width. 

Specifies the initial height of the MDI child window. If set to 

CWJJSEDEFAULT, the MDI child window is assigned a default 

height. 

Specifies additional styles for the MDI child window. The style 

field may be set to one or more of the following values: 
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IParam 



Value Meaning 

WS_MINIMIZE The MDI child window is created in a 

minimized state. 
WS_MAXIMIZE The MDI child window is created in a 

maximized state. 
WS_HSCROLL The MDI child window is created with a 

horizontal scroll bar. 
WSJVSCROLL The MDI child window is created with a 

vertical scroll bar. 

Is an application-defined 32-bit value. 



Comments When the MDI child window is created, Windows sends the 

WM_CREATE message to the window. The IParam parameter of the 
WM_CREATE message contains a pointer to a CREATESTRUCT data 
structure. The IpCreateParams field of the CREATESTRUCT structure 
contains a pointer to the MDICREATESTRUCT data structure passed with 
the WM_MDICREATE message that created the MDI child window. 



MEASUREITEMSTRUCT 



3.0 



Owner- 
draw 
control 
dimensions 



The MEASUREITEMSTRUCT data structure informs Windows of the 
dimensions of an owner-draw control. This allows Windows to process 
user interaction with the control correctly. The owner of an owner-draw 
control receives a pointer to this structure as the IParam parameter of an 
WM_MEASUREITEM message. The owner-draw control sends this 
message to its owner window when the control is created; the owner then 
fills in the appropriate fields in the structure for the control and returns. 
This structure is common to all owner-draw controls. 

The MEASUREITEMSTRUCT structure has the following format: 

record 



pedef struct tagMEASUREITEMSTRUCT 


TMeasureltemStruct = 


{ 


CtlType: Word; 


WORD CtlType; 


CtllD: Word; 


WORD CtllD; 


itemID: Word; 


WORD itemID; 


itemWidth: Word; 


WORD itemWidth; 


itemHeight: Word; 


WORD itemHeight; 


itemData: Longint; 


DWORD itemData 


end; 


} MEASUREITEMSTRUCT; 





The MEASUREITEMSTRUCT structure contains the following fields: 
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Field 



Description 



CtlType 



Is the control type. The values for control types are as follows: 



Value 

ODT_BUTTON 

ODT_COMBOBOX 

ODT_LISTBOX 

ODT MENU 



Meaning 

Owner-draw button. 
Owner-draw combo box. 
Owner-draw list box. 
Owner-draw menu. 



CtllD Is the control ID for a combo box, list box, or button. This field is 

not used for a menu. 

item ID Is the menu-item ID for a menu or the list-box item ID for a 

variable-height combo box or list box. This field is not used for a 
fixed-height combo box or list box, or for a button. 

itemWidth Specifies the width of a menu item. The owner of the owner- 

draw menu item must fill this field before returning from the 
message. 

item Height Specifies the height of an individual item in a list box or a menu. 

Before returning from the message, the owner of the owner- 
draw combo box, list box, or menu item must fill out this field. 

itemData Contains the value that was passed to the combo box or list box 

in the IParam parameter of one of the following messages: 

n CB_ADDSTRING 

□ CBJNSERTSTRING 
n LB_ADDSTRING 

□ LBJNSERTSTRING 

Contains the DWORD value passed as the IpNewItem parameter 
of the AppendMenu, InsertMenu, or ModifyMenu function that 
added or modified the menu item. Its contents are undefined for 
buttons. 

Comments Failure to fill out the proper fields in the MEASUREITEM structure will 
cause improper operation of the control. 



MENUITEMTEMPLATE 



Menu- 

it©mtGITiplClt© A complete menu template consists of a header and one or more menu- 
item lists. The following shows the structure of the menu-template 
header: 



typedef struct { 

WORD versionNumber; 

WORD offset; 
} MENUITEMTEMPLATEHEADER; 



TMenuItemTemplateHeader = record 

versionNumber: Word; 

offset: Word; 
end; 



The menu-template header contains the following fields: 
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Field 



Description 



versionNumber Specifies the version number. Should be zero. 

offset Specifies the offset from the header in bytes where the 

menu-item list begins. 

One or more MENUITEMTEMPLATE structures are combined to form the 
menu-item list. 

typedef struct { 

WORD mtOption; 

WORD mtID; 

char mtString; 
} MENUITEMTEMPLATE; 

The MENUITEMTEMPLATE structure has the following fields: 



Field 



Description 



mtOption 



mtID 



mtString 



Specifies a mask of one or more predefined menu options that 
specify the appearance of the menu item. The menu options are as 
follows: 



Value 

MF_CHECKED 
MF_END 

MF_GRAYED 

MFJTELP 

MF MENUBARBREAK 



Meaning 

Item has a checkmark next to it. 

Item must be specified for the last item in 

a pop-up menu or a static menu. 

Item is initially inactive and drawn with a 

gray effect. 

Item has a vertical separator to its left. 



MF_MENUBREAK 
MF OWNERDRAW 



MF POPUP 



Item is placed in a new column. The old 

and new columns are separated by a bar. 

Item is placed in a new column. 

The owner of the menu is responsible for 

drawing all visual aspects of the menu 

item, including highlighted, checked and 

inactive states. This option is not valid for 

a top-level menu item. 

Item displays a sublist of menu items 

when selected. 



Specifies an identification code for a nonpop-up menu item. The 
MENUITEMTEMPLATE data structure for a pop-up menu item 
does not contain the mtID field. 

Specifies a null-terminated character string that contains the name 
of the menu item. 

See also The LoadMenulndirect function in Chapter 4, "Functions directory," in 

Reference, Volume 1 . 
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METAFILEPICT 



Metafile 

picture The METAFILEPICT structure defines the metafile picture format used for 
e+n ip+i irp exchanging metafile data through the clipboard. 

typedef struct tagMETAFILEPICT { TMetaFilePict = record 
int mm; m: Integer; 

int xExt, yExt; *Ext: Integer; 

HANDLE hMF; yExt: Integer; 

} METAFILEPICT; hMF: THandle; 

end; 

The METAFILEPICT structure has the following fields: 

Field Description 

mm Specifies the mapping mode in which the picture is drawn. 

xExt Specifies the size of the metafile picture for all modes except the 

MMJSOTROPIC and MM_ANISOTROPIC modes. The x-extent 
specifies the width of the rectangle within which the picture is 
drawn. The coordinates are in units that correspond to the 
mapping mode. 

yExt Specifies the size of the metafile picture for all modes except the 

MMJSOTROPIC and MM_ANISOTROPIC modes. The y-extent 
specifies the height of the rectangle within which the picture is 
drawn. The coordinates are in units that correspond to the 
mapping mode. 

For MMJSOTROPIC and MM_ANISOTROPIC modes, which can 
be scaled, the xExt and yExt fields contain an optional suggested 
size in MMHIMETRIC units. For MM_ANISOTROPIC pictures, 
xExt and yExt can be zero when no suggested size is supplied. For 
MMJSOTROPIC pictures, an aspect ratio must be supplied even 
when no suggested size is given. (If a suggested size is given, the 
aspect ratio is implied by the size.) To give an aspect ratio without 
implying a suggested size, set xExt and yExt to negative values 
whose ratio is the appropriate aspect ratio. The magnitude of the 
negative xExt and yExt values will be ignored; only the ratio will 
be used. 

hMF Identifies a memory metafile. 
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MSG 



Message 

data 

structure 



The MSG structure contains information from the Windows application 
queue. 



typedef struct tagMSG 
HWND hwnd; 



WORD 
WORD 
LONG 
DWORD 
POINT 
MSG; 



message; 
wParam; 
lParam; 
time; 

pt; 



TMsg = record 

hwnd: HWnd; 

message: Word; 

wParam: Word; 

lParam: Longlnt; 

time: Longint; 

pt: TPoint; 
end; 



The MSG structure has the following fields: 



Field 



Description 



hwnd Identifies the window that receives the message. 

message Specifies the message number. 

wParam Specifies additional information about the message. The exact 

meaning depends on the message value. 
lParam Specifies additional information about the message. The exact 

meaning depends on the message value. 
time Specifies the time at which the message was posted. 

pt Specifies the position of the cursor (in screen coordinates) when 

the message was posted. 



MULTIKEYHELP 



Windows 

help key 

word table 

structure 



The MULTIKEYHELP structure specifies a key-word table and an 
associated key word to be used by the Windows Help application. 



typedef struct tagMULTIKEYHELP 

WORD mkSize; 

BYTE mkKeylist; 

BYTE szKeyphrase[]; 
} MULTIKEYHELP; 



TMultiKeyHelp = record 

mkSize: Word; 

mkKeyList: Byte; 

szKeyPhrase: array[0..0] of Byte; 
end; 



The MULTIKEYHELP data structure contains the following fields: 
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Field 


Description 




mkSize 
mkKeylist 
szKeyphrase[ ] 


Specifies the length of the MULTIKEYHELP structure (in 

bytes). 

Contains a single character that identifies the key-word 

table to be searched. 

Contains a null-terminated text string that specifies the 

key word to be located in the key-word table. 


OFSTRUCT 












Open-file 






structure 


The OFSTRUCT structure contains file information which results from 




opening that file. 






typedef struct tagOFSTRUCT { TOFStruct = record 

BYTE cBytes; cBytes: Byte; 

BYTE fFixedDisk; fFixedDisk: Byte; 

WORD nErrCode; nErrCode: Word; 

BYTE reserved[4]; reserved: array[0..3] of Byte; 

BYTE szPathName [120]; szPathName: array[0. .127] of Char; 
} OFSTRUCT; end; 




The OFSTRUCT structure has the following fields: 




Field 


Description 




cBytes 
fFixedDisk 

nErrCode 

reserved [4] 
szPathName[120] 


Specifies the length of the OFSTRUCT structure (in bytes). 
Specifies whether the file is on a fixed disk. The fFixedDisk 
field is nonzero if the file is on a fixed disk. 
Specifies the DOS error code if the OpenFile function 
returns -1 (that is, OpenFile failed). 
Reserved field. Four bytes reserved for future use. 
Specifies 120 bytes that contain the pathname of the file. 
This string consists of characters from the OEM character 
set. 



Chapter 7, Data types and structures 



51 



PAINTSTRUCT 



PAINTSTRUCT 



WINDOWS 

point The PAINTSTRUCT structure contains information for an application. This 
informntion information can be used to paint the client area of a window owned by 
that application. 



typedef struct tagPAINTSTRUCT 

HDC hdc; 

BOOL fErase; 

RECT rcPaint; 

BOOL fRestore; 

BOOL flncUpdate; 

BYTE rgbReserved[16]; 
} PAINTSTRUCT; 



TPaintStruct = record 

hdc: HDC; 

fErase: Bool; 

rcPaint: TRect; 

fRestore: Bool; 

flncUpdate: Bool; 

rgbReserved: array[0..15] of Byte; 
end; 



The PAINTSTRUCT structure has the following fields: 



Field 


Description 


hdc 
fErase 


Identifies the display context to be used for painting. 
Specifies whether the background has been redrawn. It 
has been redrawn if nonzero. 


rcPaint 
fRestore 


Specifies the upper-left and lower-right corners of the 
rectangle in which the painting is requested. 
Reserved field. It is used internally by Windows. 


flncUpdate 
rgbReserved[16] 


Reserved field. It is used internally by Windows. 
Reserved field. A reserved block of memory used 
internally by Windows. 



PALETTEENTRY 



3.0 



Logical 

palette 

color entry 



The PALETTEENTRY data structure specifies the color and usage of an 
entry in a logical color palette. A logical palette is defined by a 
LOG PALETTE data structure. 



typedef struct 

{ 



BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY; 



TPaletteEntry = record 

peRed: Byte; 

peGreen: Byte; 

peBlue: Byte; 

peFlags: Byte; 
end; 
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The PALETTEENTRY structure contains the following fields: 



Field 



Description 



peRed 
peGreen 
peBlue 
peFlags 



Specifies the intensity of red for the palette entry color. 
Specifies the intensity of green for the palette entry color. 
Specifies the intensity of blue for the palette entry color. 
Specifies how the palette entry is to be used. The peFlags field 
may be set to NULL or one of these values: 



Flag 

PC EXPLICIT 



PC NOCOLLAPSE 



PC RESERVED 



Meaning 

Specifies that the low-order word of the 
logical palette entry designates a hardware 
palette index. This flag allows the 
application to show the contents of the 
display-device palette. 
Specifies that the color will be placed in an 
unused entry in the system palette instead 
of being matched to an existing color in the 
system palette. If there are no unused 
entries in the system palette, the color is 
matched normally. Once this color is in the 
system palette, colors in other logical 
palettes can be matched to this color. 
Specifies that the logical palette entry will 
be used for palette animation; this prevents 
other windows from matching colors to 
this palette entry since the color will 
frequently change. If an unused system- 
palette entry is available, this color is 
placed in that entry. Otherwise, the color 
will not be available for animation. 
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POINT 



Point data 

StrUCtUTG The POINT structure defines the x- and y-coordinates of a point. 



typedef struct tagPOINT 

int x; 

int y; 
} POINT; 



TPoint = record 
x: Integer; 
y: Integer; 

end; 



The POINT structure has the following fields: 



Field 



Description 



Specifies the ^-coordinate of a point. 
Specifies the y-coordinate of a point. 



See also The ChildWindowFromPoint, PtlnRect, and WindowFromPoint functions 
in Chapter 4, "Functions directory," in Reference, Volume 1. 



RECT 



Rectangle 

data 

structure 



The RECT structure defines the coordinates of the upper-left and lower- 
right corners of a rectangle. 



Comments 



typedef struct tagRECT 

int left; 

int top; 

int right; 

int bottom; 
} RECT; 



TRect = record 

left: Integer; 

top: Integer; 

right: Integer; 

bottom: Integer; 
end; 



The RECT structure has the following fields: 



Field 



Description 



left Specifies the x-coordinate of the upper-left corner of a rectangle. 

top Specifies the y-coordinate of the upper-left corner of a rectangle. 

right Specifies the ^-coordinate of the lower-right corner of a rectangle. 

bottom Specifies the y-coordinate of the lower-right corner of a rectangle. 

The width of the rectangle defined by the RECT structure must not exceed 
32,768 units. 
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RGBQUAD 



3.0 



Rgb color 
structure 



The RGBQUAD data structure describes a color consisting of relative 
intensities of red, green, and blue. The bmiColors field of the 
BITMAPINFO data structure consists of an array of RGBQUAD data 
structures. 



typedef struct tagRGBQUAD { 



BYTE 


rgbBlue; 


BYTE 


rgbGreen; 


BYTE 


rgbRed; 


BYTE 


rgbReserved; 


RGBQUAD; 





TRGBQuad = record 

rgbBlue: Byte; 

rgbGreen: Byte; 

rgbRed: Byte; 

rgbReserved: Byte; 
end; 



The RGBQUAD structure contains the following fields: 

Field Description 

rgbBlue Specifies the intensity of blue in the color. 

rgbGreen Specifies the intensity of green in the color. 

rgbRed Specifies the intensity of red in the color. 

rgbReserved Is not used and must be set to zero. 



RGBTRIPLE 



3.0 



Rgb color 
structure 



The RGBTRIPLE data structure describes a color consisting of relative 
intensities of red, green, and blue. The bmciColors field of the 
BITMAPCOREINFO data structure consists of an array of RGBTRIPLE data 
structures. 



typedef struct 


tagRGBTRIPLE { 


TRGBTriple = record 


BYTE 


rgbtBlue; 


rgbtBlue: Byte; 


BYTE 


rgbtGreen; 


rgbtGreen: Byte; 


BYTE 


rgbtRed; 


rgbtRed: Byte; 


} RGBTRIPLE; 




end; 



The RGBTRIPLE structure contains the following fields: 



Field 



Description 



rgbtBlue Specifies the intensity of blue in the color. 

rgbtGreen Specifies the intensity of green in the color. 

rgbtRed Specifies the intensity of red in the color. 



Chapter 7, Data types and structures 



55 



TEXTMETRIC 



TEXTMETRIC 



Basic font 

m©triCS The TEXTMETRIC structure contains basic information about a physical 

font. All sizes are given in logical units; that is, they depend on the current 
mapping mode of the display context. 

TTextMetric = record 

tmHeight: Integer; 

tmAscent: Integer; 

tmDescent: Integer; 

tmlnternalLeading: Integer; 

tmExternalLeading: Integer; 

tmAveCharWidth : Integer; 

tmMaxCharWidth: Integer; 

tmWeight: Integer; 

tmltalic: Byte; 

tmUnderlined: Byte; 

tmStruckOut: Byte; 

tmFirstChar: Byte; 

tmLastChar: Byte; 

tmDefaultChar: Byte; 

tmBreakChar: Byte; 

tmPitchAndFamily: Byte; 

tmCharSet: Byte; 

tmOverhang: Integer; 

tmDigitizedAspectX: Integer; 

tmDigitizedAspectY: Integer; 
end; 

The TEXTMETRIC structure has the following fields: 



typedef i 


struct tagTEXTMETRIC { 


short 


int tmHeight; 


short 


int tmAscent; 


short 


int tmDescent; 


short 


int tmlnternalLeading; 


short 


int tmExternalLeading; 


short 


int tmAveCharWidth; 


short 


int tmMaxCharWidth; 


short 


int tmWeight; 


BYTE 


tmltalic; 


BYTE 


tmUnderlined; 


BYTE 


tmStruckOut; 


BYTE 


tmFirstChar; 


BYTE 


tmLastChar; 


BYTE 


tmDefaultChar; 


BYTE 


tmBreakChar; 


BYTE 


tmPitchAndFamily; 


BYTE 


tmCharSet; 


short 


int tmOverhang; 


short 


int tmDigitizedAspectX; 


short 


int tmDigitizedAspectY; 


} TEXTMETRIC; 



Field 



Description 



tmHeight 
tmAscent 

tmDescent 

tmlnternalLeading 

tmExternalLeading 



Specifies the height (ascent + descent) of characters. 

Specifies the ascent (units above the baseline) of 

characters. 

Specifies the descent (units below the baseline) of 

characters. 

Specifies the amount of leading (space) inside the bounds 

set by the tmHeight field. Accent marks and other foreign 

characters may occur in this area. The designer may set 

this field to zero. 

Specifies the amount of extra leading (space) that the 

application adds between rows. Since this area is outside 

the font, it contains no marks and will not be altered by 

text output calls in either OPAQUE or TRANSPARENT 

mode. The designer may set this field to zero. 
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tmMaxCharWidth 

tm Weight 

tmltalic 

tmUnderlined 

tmStruckOut 

tmFirstChar 

tmLastChar 

tmDefaultChar 

tmBreakChar 

tmPitchAndFamily 



tmAveCharWidth Specifies the average width of characters in the font 

(loosely defined as the width of the letter x). This value 
does not include overhang required for bold or italic 
characters. 

Specifies the width of the widest character in the font. 
Specifies the weight of the font. 
Specifies an italic font if it is nonzero. 
Specifies an underlined font if it is nonzero. 
Specifies a struckout font if it is nonzero. 
Specifies the value of the first character defined in the font. 
Specifies the value of the last character defined in the font. 
Specifies the value of the character that will be substituted 
for characters that are not in the font. 
Specifies the value of the character that will be used to 
define word breaks for text justification. 
Specifies the pitch and family of the selected font. The 
low-order bit specifies the pitch of the font. If it is 1, the 
font is variable pitch. If it is 0, the font is fixed pitch. The 
four high-order bits designate the font family. The 
tmPitchAndFamily field can be combined with the 
hexadecimal value OxFO by using the bitwise AND 
operator, and then be compared with the font family 
names for an identical match. For a description of the font 
families, see the LOGFONT structure, earlier in this 
chapter. 

Specifies the character set of the font. 
Specifies the per-string extra width that may be added to 
some synthesized fonts. When synthesizing some 
attributes, such as bold or italic, GDI or a device may have 
to add width to a string on both a per-character and per- 
string basis. For example, GDI makes a string bold by 
expanding the intracharacter spacing and overstriking by 
an offset value; it italicizes a font by skewing the string. In 
either case, there is an overhang past the basic string. For 
bold strings, the overhang is the distance by which the 
overstrike is offset. For italic strings, the overhang is the 
amount the top of the font is skewed past the bottom of 
the font. The tmOverhang field allows the application to 
determine how much of the character width returned by a 
GetTextExtent function call on a single character is the 
actual character width and how much is the per-string 
extra width. The actual width is the extent minus the 
overhang. 

Specifies the horizontal aspect of the device for which the 
font was designed. 

Specifies the vertical aspect of the device for which the 
font was designed. The ratio of the tmDigitizedAspectX 
and tmDigitizedAspectY fields is the aspect ratio of the 
device for which the font was designed. 

See also The GetDeviceCaps and GetTextMetrics functions in Chapter 4, 
"Functions directory," in Reference, Volume 1 . 



tmCharSet 
tmOverhang 



tmDigitizedAspectX 
tmDigitizedAspectY 
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WNDCLASS 



WNDCLASS 



Window 

ClaSS data THE WNDCLass structure contains the class attributes that are 
Structure registered by the RegisterClass function. 



typedef struct tagWNDCLASS 

WORD style; 

long (FAR PASCAL 
*lpfnWndProc) () ; 

int cbClsExtra; 

int cbWndExtra; 

HANDLE hlnstance; 

HICON hlcon; 

HCURSOR hCursor; 

HBRUSH hbrBackground; 

LPSTR IpszMenuName; 

LPSTR IpszClassName; 
} WNDCLASS; 



TWndClass = record 

style: Word; 

lpfnWndProc: TFarProc; 

cbClsExtra: Integer; 

cbWndExtra: Integer; 

hlnstance: THandle; 

hlcon: Hlcon; 

hCursor: HCursor; 

hbrBackground: HBrush; 

IpszMenuName: PChar; 

IpszClassName: PChar; 
end; 



The WNDCLASS structure has the following fields: 



Field 



Description 



style 



Value 

CS BYTEALIGNCLIENT 



CS BYTEALIGNWINDOW 



Specifies the class style. These styles can be combined by using 
the bitwise OR operator. The style field can be any 
combination of the following values: 

Meaning 

Aligns a window's client area on 

the byte boundary (in the x 

direction). 

Aligns a window on the byte 

boundary (in the x direction). 

Gives the window class its own 

display context (shared by 

instances). 

Sends double-click messages to a 

window. 

Specifies that the window class 

is an application global class. An 

application global class is 

created by an application or 

library and is available to all 

applications. The class is 

destroyed when the application 

or library that created the class 

terminates; it is essential, 



CS CLASSDC 



CS DBLCLKS 



CS GLOBALCLASS 
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WNDCLASS 



IpfnWndProc 
cbClsExtra 

cbWndExtra 



therefore, that all windows 
created with the application 
global class be closed before this 
occurs. 

CS_HREDRAW Redraws the entire window if 

the horizontal size changes. 

CS_NOCLOSE Inhibits the close option on the 

System menu. 

CS_OWNDC Gives each window instance its 

own display context. Note that 
although the CS_OWNDC style 
is convenient, it must be used 
with discretion because each 
display context occupies 
approximately 800 bytes of 
memory. 

CS_PARENTDC Gives the parent window's 

display context to the window 
class. 

CS_SAVEBITS Saves the portion of the screen 

image that is obscured by a 
window; Windows uses the 
saved bitmap to re-create a 
screen image when the window 
is removed. Windows displays 
the bitmap at its original location 
and does not send WM_PAINT 
messages to windows which had 
been obscured by the window if 
the memory used by the bitmap 
has not been discarded and if 
other screen actions have not 
invalidated the stored image. An 
application should set this bit 
only for small windows that are 
displayed briefly and then 
removed before much other 
screen activity takes place. 
Setting this bit for a window 
increases the amount of time 
required to display the window 
due to the time required to 
allocate memory to store the 
bitmap. 

CSJVREDRAW Redraws the entire window if 

the vertical size changes. 

Points to the window function. 

Specifies the number of bytes to allocate following the 

window-class structure. 

Specifies the number of bytes to allocate following the window 

instance. If an application is using the WNDCLASS structure to 
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WNDCLASS 



hlnstance 
hlcon 

hCursor 
hbrBackground 



IpszMenuName 



IpszClassName 



register a dialog box created with the CLASS directive in the 
.RC script file, it must set this field to DLGWINDOWEXTRA. 
Identifies the class module. The hlnstance field must be an 
instance handle and must not be NULL. 

Identifies the class icon. The hlcon field must be a handle to an 
icon resource. If hlcon is NULL, the application must draw an 
icon whenever the user minimizes the application's window. 
Identifies the class cursor. The hCursor field must be a handle 
to a cursor resource. If hCursor is NULL, the application must 
explicitly set the cursor shape whenever the mouse moves into 
the application's window. 

Identifies the class background brush. The hbrBackground 
field can be either a handle to the physical brush that is to be 
used for painting the background, or it can be a color value. If 
a color value is given, it must be one of the standard system 
colors listed below, and the value 1 must be added to the 
chosen color (for example, COLOR_BACKGROUND + 1 
specifies the system background color). If a color value is 
given, it must be converted to one of these HBRUSH types: 

B COLOR_ACTIVEBORDER 

b COLOR_ACTIVECAPTION 

b COLOR_APPWORKSPACE 

B COLOR_BACKGROUND 

B COLOR_BTNFACE 

B COLOR_BTNSHADOW 

B COLOR_BTNTEXT 

a COLOR_CAPTIONTEXT 

B COLOR_GRAYTEXT 

B COLOR_HIGHLIGHT 

B COLOR_HIGHLIGHTTEXT 

b COLORJNACTIVEBORDER 

B COLORJNACTIVECAPTION 

B COLOR_MENU 

B COLOR_MENUTEXT 

a COLOR_SCROLLBAR 

b COLOR_WINDOW 

b COLOR_WINDOWFRAME 

B COLOR_WINDOWTEXT 

When hbrBackground is NULL, the application must paint its 
own background whenever it is requested to paint in its client 
area. The application can determine when the background 
needs painting by processing the WM_ERASEBKGND 
message or by testing the fErase field of the PAINTSTRUCT 
structure filled by the Begin Paint function. 
Points to a null-terminated character string that specifies the 
resource name of the class menu (as the name appears in the 
resource file). If an integer is used to identify the menu, the 
MAKEINTRESOURCE macro can be used. If the 
IpszMenuName field is NULL, windows belonging to this class 
have no default menu. 

Points to a null-terminated character string that specifies the 
name of the window class. 
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Resource script statements 



This chapter describes the statements that define resources that the 
Microsoft Windows Resource Compiler (RC) adds to an application's 
executable file. See Tools for information on running the Resource 
Compiler. 

This chapter describes resource script statements in the following 
categories: 

□ Single-line statements 

□ User-defined resources 
(3 RCDATA statement 

d STRINGTABLE statement 
a ACCELERATORS statement 
n Menu statements 
d Dialog statements 
q Directives 



Single-line statements 



The single-line statements define resources that are contained in a single 
file, such as cursors, icons, and fonts. The statements associate the 
filename of the resource with an identifying name or number. The 
resource is added to the executable file when the application is created, 
and can be extracted during execution by referring to the name or 
number. 
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The following is the general form for all single-line statements: 

namelD resource-type [ [load-option] ] [[mem-option]] filename 

The namelD field specifies either a unique name or an integer value 
identifying the resource. For a font resource, namelD must be a number; it 
cannot be a name. 

The resource-type field specifies one of the following key words, which 
identify the type of resource to be loaded: 

Key word Resource Type 

CURSOR Specifies a bitmap that defines the shape of the cursor on 

the display screen. 
ICON Specifies a bitmap that defines the shape of the icon to be 

used for a given application. 
BITMAP Specifies a custom bitmap that an application is going to 

use in its screen display or as an item in a menu. 
FONT Specifies a file that contains a font. 

The optional load-option field takes a key word that specifies when the 
resource is to be loaded. The key word must be one of the following: 

Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default option. 

Icon and cursor resources can contain more than one image. If the 
resource is marked as PRELOAD, Windows loads all images in the 
resource when the application executes. 

The optional mem-option field takes the following key word or key words, 
which specify whether the resource is fixed or moveable and whether it is 
discardable: 

Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to compact 

memory. 
DISCARDABLE Resource can be discarded if no longer needed. 

The default is MOVEABLE and DISCARDABLE for cursor, icon, and font 
resources. The default for bitmap resources is MOVEABLE. 

The filename field is an ASCII string that specifies the DOS filename of the 
file that contains the resource. A full pathname must be given if the file is 
not in the current working directory. 
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The following example demonstrates the correct usage for a single-line 
statement: 

cursor CURSOR point. cur 

cursor CURSOR DISCARDABLE point. cur 

10 CURSOR custom. cur 

desk ICON desk.ico 

desk ICON DISCARDABLE desk.ico 

11 ICON custom. ico 

disk BITMAP disk.bmp 

disk BITMAP DISCARDABLE disk.bmp 

12 BITMAP custom.bmp 

5 FONT CMROMAN.FNT 



User-defined resources 



An application can also define its own resource. The resource can be any 
data that the application intends to use. A user-defined resource 
statement has the following form: 

namelD typelD [[load-option]] [[mem-option]] {[[filename]] I 

[[BEGIN 

raw-data 

END]]} 

The namelD field specifies either a unique name or an integer value that 
identifies the resource. 

The typelD field specifies either a unique name or an integer value that 
identifies the resource type. If a number is given, it must be greater than 
255. The numbers 1 through 255 are reserved for existing and future 
predefined resource types. 

The optional load-option field takes a key word that specifies when the 
resource is to be loaded. The key word must be one of the following: 

Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default option. 

The optional mem-option field takes the following key word or key words, 
which specify whether the resource is fixed or moveable and whether it is 
discardable: 
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Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to compact 

memory. This is the default option. 
DISCARDABLE Resource can be discarded if it is no longer needed. 

The optional filename field is an ASCII string that specifies the DOS 
filename of the file that contains the resource. A full pathname must be 
given if the file is not in the current working directory. Do not use the 
filename field if you supply raw data between the optional BEGIN and END 
statements. 

The raw-data field specifies one or more integers and strings. Integers can 
be in decimal, octal, or hexadecimal format. Do not use raw-data field and 
the BEGIN and END statements if you specify a filename. 

The following example demonstrates the correct usage for user-defined 
statements: 



array MYRES 


data 


.res 




14 300 


custom. res 




18 MYRES2 








BEGIN 








"Here is a 


data sti 


ring\0\ 


/* A string. Note: explicitly 
null-terminated */ 


1024, 






/* int */ 


0x029a, 






/* hex int */ 


0o733, 






/* octal int */ 


"\07" 






/* octal byte */ 


END 









Rcdata statement 



Syntax namelD RCDATA [[load-option]] [[mem-option]] 
BEGIN 
raw-data 
END 

The RCDATA statement defines a raw data resource for an application. 
Raw data resources permit the inclusion of binary data directly in the 
executable file. 

The namelD field specifies either a unique name or an integer value that 
identifies the resource. 
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The optional load-option field takes a key word that specifies when the 
resource is to be loaded. It must be one of the following: 

Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default option. 

The optional mem-option field takes the following key word or key words, 
which specify whether the resource is fixed or moveable and whether it is 
discardable: 

Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to compact 

memory. 
DISCARDABLE Resource can be discarded if no longer needed. 

The default is MOVEABLE and DISCARDABLE. 

The raw-data field specifies one or more integers and strings. Integers can 
be in decimal, octal, or hexadecimal format. 

The following example demonstrates the correct usage for the RCDATA 
statement: 

resname RCDATA 
BEGIN 

"Here is a data string\0", /* A string. Note: explicitly 

null-terminated */ 

1024, /* int */ 

0x029a, /* hex int */ 

0o733, /* octal int */ 

"\07" /* octal byte */ 

END 



Stringtable statement 



Syntax stringtable [[load-option]] [[mem-option]] 
BEGIN 
stringID string 
END 

The STRINGTABLE statement defines one or more string resources for an 
application. String resources are simply null-terminated ASCII strings that 
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can be loaded when needed from the executable file, using the LoadString 
function. 

The optional load-option field takes a key word that specifies when the 
resource is to be loaded. It must be one of the following: 

Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default option. 

The optional mem-option field takes the following key word or key words, 
which specify whether the resource is fixed or moveable and whether or 
not it is discardable: 

Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to compact 

memory. 
DISCARDABLE Resource can be discarded if no longer needed. 

The default is MOVEABLE and DISCARDABLE. 

The stringID field specifies an integer value that identifies the resource. 

The string field specifies one or more ASCII strings, enclosed in double 
quotation marks. The string must be no longer than 255 characters and 
must occupy a single line in the source file. To add a carriage return to the 
string, use this character sequence: \012. For example, "Line one\012Line 
two" would define a string that would be displayed as follows: 

Line one 
Line two 

Grouping strings in separate segments allows all related strings to be read 
in at one time and discarded together. When possible, an application 
should make the table moveable and discardable. The Resource Compiler 
allocates 16 strings per segment and uses the identifier value to determine 
which segment is to contain the string. Strings with the same upper 12 bits 
in their identifiers are placed in the same segment. 

The following example demonstrates the correct usage of the 
STRINGTABLE statement: 

tdefine IDS_HELL0 1 
#define IDS_G00DBYE 2 

STRINGTABLE 
BEGIN 
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IDS_HELLO, "Hello" 
IDS_G00DBYE, "Goodbye'' 
END 



Accelerators statement 



Syntax acctablename ACCELERATORS 
BEGIN 
event, idvalue, [[type]] [[NOINVERT]] [[ALT]] [[SHIFT]] [[CONTROL]] 

END 

The ACCELERATORS statement defines one or more accelerators for an 
application. An accelerator is a key stroke defined by the application to 
give the user a quick way to perform a task. The TranslateAccelerator 
function is used to translate accelerator messages from the application 
queue into WM_COMMAND or WM_SYSCOMMAND messages. 

The acctablename field specifies either a unique name or an integer value 
that identifies the resource. 

The event field specifies the key stroke to be used as an accelerator. It can 
be any one of the following: 

Character Description 

"char" A single ASCII character enclosed in double quotes. The 

character can be preceded by a caret ( A ), meaning that 
the character is a control character. 

ASCII character An integer value representing an ASCII character. The 

type field must be ASCII. 

Virtual key character An integer value representing a virtual key. The virtual 
key for alphanumeric keys can be specified by placing 
the uppercase letter or number in double quotation 
marks (for example, "9" or "C"). The type field must be 
VIRTKEY. 

The idvalue field specifies an integer value that identifies the accelerator. 

The type field is required only when event is an ASCII character or a 
virtual key character. The type field specifies either ASCII or VIRTKEY; the 
integer value of event is interpreted accordingly. When VIRTKEY is 
specified and the event field contains a string, the event field must be 
uppercase. 
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The NOINVERT option, if given, means that no top-level menu item is 
highlighted when the accelerator is used. This is useful when defining 
accelerators for actions such as scrolling that do not correspond to a menu 
item. If NOINVERT is omitted, a top-level menu item will be highlighted 
(if possible) when the accelerator is used. 

The ALT option, if given, causes the accelerator to be activated only if the 
ALT key is down. 

The SHIFT option, if given, causes the accelerator to be activated only if 
the SHIFT key is down. 

The CONTROL option, if given, defines the character as a control character 
(the accelerator is only activated if the CONTROL key is down). This has the 
same effect as using a caret ( A ) before the accelerator character in the event 
field. 

The ALT, SHIFT, and CONTROL options apply only to virtual keys. 

The following example demonstrates the correct usage of accelerator keys: 



1 ACCELERATORS 






BEGIN 






" A C", 


IDDCLEAR 


control C 




"K", 


IDDCLEAR 


shift K 




"k", 


IDDELLIPSE, ALT 


alt K 




98, 


IDDRECT, ASCII 


b 




66, 


IDDSTAR, ASCII 


B (shift b) 




"g", 


IDDRECT 


g 




"G", 


IDDSTAR 


G (shift G) 




VK_F1, 


IDDCLEAR, VIRTKEY 


Fl 


VK_F1, 


IDDSTAR, CONTROL, VIRTKEY 


control Fl 


VK_F1, 


IDDELLIPSE, SHIFT, VIRTKEY 


shift Fl 


VK_F1, 


IDDRECT, ALT, VIRTKEY 


alt Fl 


VK_F2, 


IDDCLEAR, ALT, SHIFT, VIRTKEY 


alt shift F2 


VK_F2, 


IDDSTAR, CONTROL, SHIFT, VIRTKEY 


Ctrl shift F2 


VK_F2, 


IDDRECT, ALT, CONTROL, VIRTKEY 


alt control F2 


END 









Menu statement 



Syntax menuID MENU [[load-option]] [[mem-option]] 
BEGIN 

item-definitions 
END 
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The MENU statement defines the contents of a menu resource. A menu 
resource is a collection of information that defines the appearance and 
function of an application menu. A menu is a special input tool that lets a 
user select commands from a list of command names. 

The menuID field specifies a name or number used to identify the menu 
resource. 

The optional load-option field takes a key word that specifies when the 
resource is to be loaded. It must be one of the following: 

Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default option. 

The optional mem-option field takes the following key word or key words, 
which specify whether the resource is fixed or moveable and whether it is 
discardable: 

Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved to compact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 

The default is MOVEABLE and DISCARDABLE. 

The item-definition field specifies special resource statements that define 
the items in the menu. These statements are defined in the following 
sections. The following is an example of a complete MENU statement: 

sample MENU 
BEGIN 

MENUITEM "&Soup", 100 
MENUITEM "S&alad", 101 
POPUP "SEntree" 
BEGIN 

MENUITEM "SFish", 200 

MENUITEM "SChicken", 201, CHECKED 

POPUP "SBeef" 

BEGIN 

MENUITEM "SSteak", 301 
MENUITEM "SPrime Rib", 302 
END 
END 

MENUITEM "SDessert", 103 
END 
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Item- 
definition 
statements 



The MENUITEM and POPUP statements are used in the item-definition 
section of a menu statement to define the names and attributes of the 
actual menu items. Any number of statements can be given; each defines a 
unique item. The order of the statements defines the order of the menu 
items. 

The MENUITEM and POPUP statements can be used only within an item- 
definition section of a MENU statement. 



MENUITEM 



Syntax MENUITEM text, result, [[optionlist]] 

This optional statement defines a menu item. 

The text field takes an ASCII string, enclosed in double quotation marks, 
that specifies the name of the menu item. 

The string can contain the escape characters \t and \a. The \t character 
inserts a tab in the string and is used to align text in columns. Tab 
characters should be used only in pop-up menus, not in menu bars. (See 
the following section for information on pop-up menus.) The \a character 
aligns all text that follows it flush right to the menu bar or pop-up menu. 

To insert a double quotation mark (") in the string, use two double 
quotation marks ("")• 

To add a mnemonic to the text string, place the ampersand (&) ahead of 
the letter that will be the mnemonic. This will cause the letter to appear 
underlined in the control and to function as the mnemonic. To use the 
ampersand as a character in a string, insert two ampersands (&&). 

The result field takes an integer value that specifies the result generated 
when the user selects the menu item. Menu-item results are always 
integers; when the user clicks the menu-item name, the result is sent to the 
window that owns the menu. 

The optional optionlist field takes one or more predefined menu options, 
separated by commas or spaces, that specify the appearance of the menu 
item. The menu options are as follows: 
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Option 

CHECKED 
GRAYED 

HELP 

INACTIVE 

MENUBARBREAK 



Description 

Item has a checkmark next to it. 

Item name is initially inactive and appears on the menu in 
gray or a lightened shade of the menu-text color. 
Item has a vertical separator to its left. 
Item name is displayed, but it cannot be selected. 
Same as MF_MENUBREAK except that for pop-up menus, 
it separates the new column from the old column with a 
vertical line. 
MENU BREAK Places the menu item on a new line for static menu-bar 

items. For pop-up menus, places the menu item in a new 
column, with no dividing line between the columns. 

The INACTIVE and GRAYED options cannot be used together. 

The following example demonstrates the correct usage of the MENUITEM 
statement: 

MENUITEM "&Alpha", 1, CHECKED, GRAYED 
MENUITEM "SBeta", 2 



PQPUP 

Syntax POPUP text, [[optionlist]] 
BEGIN 

item-definitions 
END 

This statement marks the beginning of the definition of a pop-up menu. A 
pop-up menu (which is also known as a drop-down menu) is a special 
menu item that displays a sublist of menu items when it is selected. 

The text field takes an ASCII string, enclosed in double quotation marks, 
that specifies the name of the pop-up menu. 

The optional optionlist field takes one or more predefined menu options 
that specify the appearance of the menu item. The menu options are as 
follows: 



Option 



Description 



CHECKED 

GRAYED 

INACTIVE 



Item has a checkmark next to it. This option is not valid 

for a top-level pop-up menu. 

Item name is initially inactive and appears on the menu in 

gray or a lightened shade of the menu-text color. 

Item name is displayed, but it cannot be selected. 
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MENUBARBREAK Same as MF_MENUBREAK except that for pop-up menus, 

it separates the new column from the old column with a 
vertical line. 

MENUBREAK Places the menu item on a new line for static menu-bar 

items. For pop-up menus, places the menu item in a new 
column, with no dividing line between the columns. 

The options can be combined using the bitwise OR operator. The 
INACTIVE and GRAYED options cannot be used together. 

The item-definitions field can specify any number of MENUITEM or POPUP 
statements. As a result, any pop-up menu item can display another pop- 
up menu. 

The following example demonstrates the correct usage of the POPUP 
statement: 

chem MENU 
BEGIN 

POPUP "&Elements" 
BEGIN 

MENUITEM "SOxygen", 200 

MENUITEM "SCarbon", 201, CHECKED 

MENUITEM "SHydrogen", 202 

MENUITEM "SSulfur", 203 

MENUITEM "Ch&lorine", 204 
END 



POPU 


P "&Compounds" 






BEGIN 








POPUP "SSugars" 








BEGIN 








MENUITEM "SGlucose" 


, 301 






MENUITEM "SSucrose" 


, 302, 


CHECKED 




MENUITEM "&Lactose" 


, 303, 


MENUBREAK 




MENUITEM "SFructose 


", 304 






END 








POPUP "SAcids" 








BEGIN 








"&Hydrochloric", 


401 






"SSulfuric", 402 








END 






END 








END 
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MENUITEM 

SEPARATOR 

Syntax MENUITEM SEPARATOR 

This special form of the MENUITEM statement creates an inactive menu 
item that serves as a dividing bar between two active menu items in a 
pop-up menu. 

The following demonstrates the correct usage of the MENUITEM 
SEPARATOR statement: 

MENUITEM "SRoman", 206 
MENUITEM SEPARATOR 
MENUITEM "&20 Point", 301 

DIALOG statement 

The DIALOG statement defines a template that can be used by an 
application to create dialog boxes. 

Syntax namelD DIALOG [[load-option]] [[mem-option]] x, y, width, height 
[[option-statements]] 
BEGIN 

control-statements 
END 

This statement marks the beginning of a DIALOG template. It defines the 
name of the dialog box, the memory and load options, the box's starting 
location on the display screen, and the box's width and height. 

The namelD field specifies either a unique name or an integer value that 
identifies the resource. 

The optional load-option field takes a key word that specifies when the 
resource is to be loaded. It must be one of the following: 

Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default option. 

The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 

FIXED Resource remains at a fixed memory location. 
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MOVEABLE Resource can be moved if necessary in order to compact 

memory. This is the default option. 
DISCARDABLE Resource can be discarded if no longer needed. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the dialog box. The horizontal units are 1 /4 of 
the dialog base width unit; the vertical units are 1 /8 of the dialog base 
height unit. The current dialog base units are computed from the height 
and width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The exact meaning of the 
coordinates depends on the style defined by the STYLE option statement. 
For child-style dialog boxes, the coordinates are relative to the origin of 
the parent window, unless the dialog box has the style DS_ABSALIGN; in 
that case, the coordinates are relative to the origin of the display screen. 

The width and height fields take integer values that specify the width and 
height of the box. The width units are 1 /4 of the dialog base width unit; 
the height units are 1/8 of the dialog base height unit. 

The option and control statements are described in the following sections. 

The following demonstrates the correct usage of the DIALOG statement: 

finclude "WINDOWS. H" 

errmess DIALOG 10, 10, 300, 110 

STYLE WS_POPUP|WS_BORDER 

CAPTION "Error!" 

BEGIN 

CTEXT "Select One:", 1, 10, 10, 280, 12 

RADIOBUTTON "SRetry", 2, 75, 30, 60, 12 

RADIOBUTTON "SAbort", 3, 75, 50, 60, 12 

RADIOBUTTON "Slgnore", 4, 75, 80, 60, 12 
END 

Comments Do not use the WS_CHILD style with a modal dialog box. The DialogBox 
function always disables the parent/owner of the newly-created dialog 
box. When a parent window is disabled, its child windows are implicitly 
disabled. Since the parent window of the child-style dialog box is 
disabled, the child-style dialog box is too. 

If a dialog box has the DS_ABSALIGN style, the dialog coordinates for its 
upper-left corner are relative to the screen origin instead of to the upper- 
left corner of the parent window. You would typically use this style when 
you wanted the dialog box to start in a specific part of the display no 
matter where the parent window may be on the screen. 
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The name DIALOG can also be used as the class-name parameter to the 
CreateWindow function in order to create a window with dialog-box 
attributes. 



Dialog 

option 

statements 



The dialog option statements, given in the option-statements section of the 
DIALOG statement, define special attributes of the dialog box, such as its 
style, caption, and menu. The option statements are optional. If the 
application does not supply a particular option statement, the dialog box 
is given default attributes for that option. Dialog option statements 
include the following: 

a STYLE 

□ CAPTION 

□ MENU 

□ CLASS 
a FONT 

The option statements are discussed individually in the following 
sections. 



STYLE 



Syntax STYLE style 



This optional statement defines the window style of the dialog box. The 
window style specifies whether the box is a pop-up or a child window. 
The default style has the following attributes: 

WS_POPUP 
WS_BORDER 

WS_SYSMENU 

The style field takes an integer value or predefined name that specifies the 
window style. It can be any of the window styles defined in Table 8.1, 
"Window styles." 



Comments 



Table 8.1 
Window styles 



If the predefined names are used, the #include directive must be used so 
that the WINDOWS.H file will be included in the resource script. 



Style 



DS LOCALEDIT 



Meaning 



Specifies that edit controls in the dialog box will use 
memory in the application's data segment. By default, all 
edit controls in dialog boxes use memory outside the 
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Table 8.1 : Window styles (continued) 



DS MODALFRAME 



DS NOIDLEMSG 



DS_SYSMODAL 

WS_BORDER 

WS_CAPTION 

WS_CHILD 

WS_CHILDWINDOW 
WS CLIPCHILDREN 



WS CLIPSIBLINGS 



application's data segment. This feature can be 

suppressed by adding the DS_LOCALEDIT flag to the 

STYLE command for the dialog box. If this flag is not 

used, EM_GETHANDLE and EM_SETHANDLE 

messages must not be used since the storage for the 

control is not in the application's data segment. This 

feature does not affect edit controls created outside of 

dialog boxes. 

Creates a dialog box with a modal dialog-box frame that 

can be combined with a title bar and system menu by 

specifying the WS_CAPTION and WS_SYSMENU styles. 

Suppresses WM_ENTERIDLE messages that Windows 

would otherwise send to the owner of the dialog box 

while the dialog box is displayed. 

Creates a system-modal dialog box. 

Creates a window that has a border. 

Creates a window that has a title bar (implies 

WS_BORDER). 

Creates a child window. It cannot be used with 

WS_POPUP. 

Creates a child window that has the style WS_CHILD. 

Excludes the area occupied by child windows when 

drawing within the parent window. Used when creating 

the parent window. 

Clips child windows relative to each other; that is, when 

a particular child window receives a WP_PAINT 

message, this style clips all other top-level child 

windows out of the region of the child window to be 

updated. (If WS_CLIPSIBLINGS is not given and child 

windows overlap, it is possible, when drawing in the 

client area of a child window, to draw in the client area 

of a neighboring child window.) For use with 

WS_CHILD only. 

Creates a window that is initially disabled. 

Creates a window with a modal dialog-box frame but no 

title. 

Specifies the first control of a group of controls in which 

the user can move from one control to the next by using 

the arrow keys. All controls defined with the 

WS_GROUP style after the first control belong to the 

same group. The next control with the WS_GROUP style 

ends the style group and starts the next group (i.e., one 

group ends where the next begins). This style is valid 

only for controls. 

Creates a window that has a horizontal scroll bar. 

Creates a window that is initially iconic. For use with 

WS_OVERLAPPED only. 

Creates a window of maximum size. 

Creates a window that has a Maximize box. 

Creates a window of minimum size. 

Creates a window that has a Minimize box. 



WS_DISABLED 
WS_DLGFRAME 

WS GROUP 



WS_HSCROLL 
WSJCONIC 

WS_MAXIMIZE 
WS_MAXIMIZEBOX 
WS_MINIMIZE 
WS MINIMIZEBOX 
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Table 8.1: Window styles (continued) 



WS POPUP 



WS_OVERLAPPED Creates an overlapped window. An overlapped window 

has a caption and a border. 

WS_OVERLAPPEDWINDOW 

Creates an overlapped window having the 

WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, 

WSJTHICKFRAME, WS_MINIMIZEBOX, and 

WS_MAXIMIZEBOX styles. 

Creates a pop-up window. It cannot be used with 

WS_CHILD. 

WS_POPUPWINDOW Creates a pop-up window that has the styles 

WS_POPUP, WS_BORDER, and WS_SYSMENU. The 

WS_CAPTION style must be combined with the 

WS_POPUPWINDOW style to make the system menu 

visible. 

Creates a window that has a size box. Used only for 

windows with a title bar or with vertical and horizontal 

scroll bars. 

Creates a window that has a System-menu box in its title 

bar. Used only for windows with title bars. If used with a 

child window, this style creates a Close box instead of a 

System-menu box. 

Specifies one of any number of controls through which 

the user can move by using the TAB key. The TAB key 

moves the user to the next control specified by the 

WS_TABSTOP style. This style is valid only for controls. 

WS_THICKFRAME Creates a window with a thick frame that can be used to 

size the window. 

Creates a window that is initially visible. This applies to 
overlapping and pop-up windows. For overlapping 
windows, the y parameter is used as a ShowWindow 
function parameter. 
Creates a window that has a vertical scroll bar. 



WS SIZEBOX 



WS SYSMENU 



WS TABSTOP 



WS VISIBLE 



WS VSCROLL 



CAPTION 



Syntax CAPTION captiontext 



This optional statement defines the dialog box's title. The title appears in 
the box's caption bar (if it has one). 

The default caption is empty. 

The captiontext field specifies an ASCII character string enclosed in double 
quotation marks. 

The following example demonstrates the correct usage of the CAPTION 
statement: 

CAPTION "Error!" 
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MENU 

Syntax MENU menuname 

This optional statement defines the dialog box's menu. If no statement is 
given, the dialog box has no menu. 

The menuname field specifies the resource name or number of the menu to 
be used. 

The following example demonstrates the correct usage of the MENU 
statement: 

MENU errmenu 



CLASS 



Syntax CLASS class 

This optional statement defines the class of the dialog box. If no statement 
is given, the Windows standard dialog class will be used as the default. 

The class field specifies an integer or a string, enclosed in double quotation 
marks, that identifies the class of the dialog box. If the window procedure 
for the class does not process a message sent to it, it must call the 
DefDIgProc function to ensure that all messages are handled properly for 
the dialog box. A private class can use DefDIgProc as the default window 
procedure. The class must be registered with the cbWnd Extra field of the 
WNDCLASS data structure set to DLGWINDOWEXTRA. 

The following example demonstrates the correct usage of the CLASS 
statement: 

CLASS "myclass" 

Comments The CLASS statement should be used with special cases, since it overrides 
the normal processing of a dialog box. The CLASS statement converts a 
dialog box to a window of the specified class; depending on the class, this 
could give undesirable results. Do not use the predefined control class 
names with this statement. 
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FONT 



Syntax FONT pointsize, typeface 

This optional statement defines the font with which Windows will draw 
text in the dialog box. The font must have been previously loaded, either 
from WIN.INI or by calling Load Font. 

The pointsize field is an integer that specifies the size in points of the font. 

The typeface field specifies an ASCII character string enclosed in double 
quotation marks that specifies the name of the typeface. This name must 
be identical to the name defined in the [fonts] section of WIN.INI. 

The following example demonstrates the correct usage of the FONT 
statement: 

FONT 12, "Helv" 



Dialog 

control 

statements 



The dialog control statements, given in the control-statements section of the 
DIALOG statement, define the attributes of the control windows that 
appear in the dialog box. A dialog box is empty unless one or more 
control statements are given. Control statements include the following: 

□ LTEXT 

□ RTEXT 

□ CTEXT 

a CHECKBOX 

□ PUSHBUTTON 

□ LISTBOX 
pGROUPBOX 

p DEFPUSHBUTTON 

□ RADIOBUTTON 

□ ED1TTEXT 
□COMBOBOX 

□ ICON 

□ SCROLLBAR 

□ CONTROL 

The control statements are discussed individually in the following 
sections. For more information on control classes and styles, see Tables 
8.2, "Control classes," and 8.3, "Control styles." 
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LTEXT 



Syntax LTEXT text, id, x, y, width, height, [[style]] 

This statement defines a flush-left text control. It creates a simple rectangle 
that displays the given text flush-left in the rectangle. The text is 
formatted before it is displayed. Words that would extend past the end of 
a line are automatically wrapped to the beginning of the next line. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

d WS_TABSTOP 
hWS_GROUP 

These styles are described in Table 8.1, "Window styles." Styles can be 
combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for LTEXT is SS_LEFT and WS_GROUP. 

The following example demonstrates the correct usage of the LTEXT 
statement: 



80 



Software development kit 



LTEXT "Enter Name:", 3, 10, 10, 40, 1C 



RTEXT 



Syntax RTEXT text, id, x, y, width, height, [{style\\ 

This statement defines a flush-right text control. It creates a simple 
rectangle that displays the given text flush-right in the rectangle. The text 
is formatted before it is displayed. Words that would extend past the end 
of a line are automatically wrapped to the beginning of the next line. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

d WS_TABSTOP 
nWS_GROUP 

These styles are described in Table 8.1, "Window styles." Styles can be 
combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for RTEXT is SS_RIGHT and WS_GROUP. 

The following example demonstrates the correct usage of the RTEXT 
statement: 



Chapter 8, Resource script statements 



81 



RTEXT "Number of Messages", 4, 30, 50, 100, 10 



CTEXT 



Syntax CTEXT text, id, x, y, width, height, [{style]] 

This statement defines a centered text control. It creates a simple rectangle 
that displays the given text centered in the rectangle. The text is formatted 
before it is displayed. Words that would extend past the end of a line are 
automatically wrapped to the beginning of the next line. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

■ WSJTABSTOP 

■ WS_GROUP 

These styles are described in Table 8.1, "Window styles." Styles can be 
combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for CTEXT is SS_CENTER and WS_GROUP. 

The following example demonstrates the correct usage of the CTEXT 
statement: 
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CTEXT "Title", 3, 10, 50, 40, 10 



CHECKBOX 



Syntax CHECKBOX text, id, x, y, width, height, [[style]] 

This statement defines a check-box control belonging to the BUTTON 
class. It creates a small rectangle (check box) that is highlighted when 
clicked. The given text is displayed just to the right of the check box. The 
control highlights the rectangle when the user clicks the mouse in it, and 
removes the highlight on the next click. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

nWSJTABSTOP 
nWS_GROUP 

These styles are described in Table 8.1, "Window styles." 

In addition to these styles, the style field may contain any combination (or 
none) of the BUTTON-class styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 
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PUSHBUTTON 



The default style for CHECKBOX is BS_CHECKBOX and WS_TABSTOP. 

The following example demonstrates the correct usage of the CHECKBOX 
statement: 

CHECKBOX "Arabic", 3, 10, 10, 40, 10 



Syntax PUSHBUTTON text, id, x, y, width, height, [[style]] 

This statement defines a push-button control belonging to the BUTTON 
class. It creates a rectangle containing the given text. The control sends a 
message to its parent whenever the user clicks the mouse inside the 
rectangle. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

■ WS_TABSTOP 

■ WS_DISABLED 

■ WS_GROUP 

These styles are described in Table 8.1, "Window styles." 
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In addition to these styles, the style field may contain any combination (or 
none) of the BUTTON-class styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for PUSHBUTTON is BS_PUSHBUTTON and 
WS_TABSTOP. 

The following example demonstrates the correct usage of the 
PUSHBUTTON statement: 



LISTBOX 



PUSHBUTTON "ON", 7, 10, 10, 20, 1( 



Syntax LISTBOX id, x, y, width, height, [[style]] 

This statement defines a list box belonging to the LISTBOX class. It creates 
a rectangle that contains a list of strings (such as filenames) from which 
the user can make selections. 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

a WS_BORDER 
a WS_VSCROLL 

These styles are described in Table 8.1, "Window styles." 
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In addition to these styles, the style field may contain any combination (or 
none) of the LISTBOX-class styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for LISTBOX is LBS_NOTIFY, WS_VSCROLL, and 
WS_BORDER. 

For information on the recommended keys for use in list-box controls, see 
the System Application Architecture, Common User Access: Advanced Interface 
Design Guide. 

The following example demonstrates the correct usage of the LISTBOX 
statement: 



GROUPBOX 



LISTBOX 666, 10, 10, 50, 54 



Syntax GROUPBOX text, id, x, y, width, height, [[style]] 

This statement defines a group box belonging to the BUTTON class. It 
creates a rectangle that groups other controls together. The controls are 
grouped by drawing a border around them and displaying the given text 
in the upper-left corner. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. Selecting the mnemonic moves the input focus 
to the next control in the group, in the order set in the resource file. To use 
the ampersand as a character in a string, insert two ampersands (&&). 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 
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The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

n WS_TABSTOP 
□ WS_DISABLED 

These styles are described in Table 8.1, "Window styles." 

In addition to these styles, the style field may contain any combination (or 
none) of the BUTTON-class styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for GROUPBOX is BS_GROUPBOX and WS_TABSTOP. 

The following example demonstrates the correct usage of the GROUPBOX 
statement: 



GROUPBOX "Output", 42, 10, 10, 30, 50 



DEFPUSHBUTTON 



Syntax DEFPUSHBUTTON text, id, x, y, width, height, [[style]] 

This statement defines a default push-button control that belongs to the 
BUTTON class. It creates a small rectangle with a bold outline that 
represents the default response for the user. The given text is displayed 
inside the button. The control highlights the button in the usual way when 
the user clicks the mouse in it and sends a message to its parent window. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
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width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

d WS_TABSTOP 
■ WS_GROUP 
hWS_DISABLED 

These styles are described in Table 8.1, "Window styles." 

In addition to these styles, the style field may contain any combination (or 
none) of the BUTTON-class styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for DEFPUSHBUTTON is BS_DEFPUSHBUTTON and 
WS_TABSTOP. 

The following example demonstrates the correct usage of the 
DEFPUSHBUTTON statement: 



DEFPUSHBUTTON "ON", 7, 10, 10, 20, 1C 



RADIOBUTTON 



Syntax RADIOBUTTON text, id, x, y, width, height, [[style]] 

This statement defines a radio-button control belonging to the BUTTON 
class. It creates a small circle that has the given text displayed just to its 
right. The control highlights the button when the user clicks the mouse in 
it and sends a message to its parent window. The control removes the 
highlight and sends a message on the next click. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

□ WS_TABSTOP 

nWS_GROUP 

nWS_DISABLED 

These styles are described in Table 8.1, "Window styles." 

In addition to these styles, the style field may contain any combination (or 
none) of the BUTTON-class styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for RADIOBUTTON is BS_RADIOBUTTON and 
WS_TABSTOP. 

The following example demonstrates the correct usage of the 
RADIOBUTTON statement: 



RADIOBUTTON "AM 101", 10, 10, 10, 40, 10 



EDITTEXT 



Syntax EDITTEXT id, x, y, width, height, [[style]] 

This statement defines an EDIT control belonging to the EDIT class. It 
creates a rectangular region in which the user can enter and edit text. The 
control displays a cursor when the user clicks the mouse in it. The user 
can then use the keyboard to enter text or edit the existing text. Editing 
keys include the BACKSPACE and DELETE keys. The user can also use the 
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mouse to select characters to be deleted, or to select the place to insert new 
characters. 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBasellnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

nWSJTABSTOP 
nWS_GROUP 
oWS_VSCROLL 
■ WSJHSCROLL 
dWS_DISABLED 

These styles are described in Table 8.1, "Window styles." 

In addition to these styles, the style field may contain any combination (or 
none) of the EDIT-class styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. The EDIT-class 
styles must not conflict with each other. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for EDITTEXT is WSJTABSTOP, ES_LEFT, and 
WS_BORDER. 

Keyboard use is predefined for edit controls. Predefined keys are listed in 
the System Application Architecture, Common User Access: Advanced Interface 
Design Guide. 

The following example demonstrates the correct usage of the EDITTEXT 
statement: 

EDITTEXT 3, 10, 10, 100, 10 
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COMBOBOX 



Syntax COMBOBOX id, x, y, width, height, [[style]] 

This statement defines a combo box belonging to the COMBOBOX class. 
A combo box consists of either a static text field or edit field combined 
with a list box. The list box can be displayed at all times or pulled down 
by the user. If the combo box contains a static text field, the text field 
always displays the selection (if any) in the list-box portion of the combo 
box. If it uses an edit field, the user can type in the desired selection; the 
list box highlights the first item (if any) which matches what the user has 
entered in the edit field. The user can then select the item highlighted in 
the list box to complete the choice. In addition, the combo box can be 
owner-draw and of fixed or variable height. 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

n WS_TABSTOP 
□ WS_GROUP 
aWSJVSCROLL 
aWS_DISABLED 

These styles are described in Table 8.1, "Window styles." 

In addition to these styles, the style field may contain any combination (or 
none) of the combo-box styles described in Table 8.3, "Control styles." 
Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 
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The default style for COMBOBOX is WS_TABSTOP and CBS_SIMPLE. 

The following example demonstrates the correct usage of the COMBOBOX 
statement: 

COMBOBOX 777, 10, 10, 50, 54, CBS SIMPLE | WS VSCROLL | WS TABSTOP 



ICON 



Syntax ICON text, id, x, y, width, height, [[style]] 

This statement defines an icon control belonging to the STATIC class. It 
creates an icon displayed in the dialog box. 

The text field specifies the name of an icon (not a filename) defined 
elsewhere in the resource file. 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

For the ICON statement, the width and height fields are ignored; the icon 
automatically sizes itself. 

The optional style field allows only the SS_ICON style. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

The default style for ICON is SSJCON. 

The following example demonstrates the correct usage of the ICON 
statement: 

ICON "myicon" 901, 30, 30 
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SCROLLBAR 



Syntax SCROLLBAR id, x, y, width, height, [[style]] 

This statement defines a scroll-bar control belonging to the SCROLLBAR 
class. It is a rectangle that contains a scroll thumb and has direction 
arrows at both ends. The scroll-bar control sends a notification message to 
its parent whenever the user clicks the mouse in the control. The parent is 
responsible for updating the thumb position. Scroll-bar controls can be 
positioned anywhere in a window and used whenever needed to provide 
scrolling input. 

The id field takes a unique integer value that identifies the control. 

The x and y fields take integer values that specify the location of the 
upper-left corner of the control in dialog units relative to the origin of the 
dialog box. The horizontal units are 1 /4 of the dialog base width unit; the 
vertical units are 1/8 of the dialog base height unit. The current dialog 
base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in 
pixels. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 

The optional style field can contain any combination (or none) of the 
following styles: 

nWS_TABSTOP 
□ WS_GROUP 
nWS_DISABLED 

These styles are described in Table 8.1, "Window styles." 

In addition to these styles, the style field may contain any combination (or 
none) of the SCROLLBAR-class styles described in Table 8.3, "Control 
styles." Styles can be combined using the bitwise OR operator. 

Comments The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 
The default style for SCROLLBAR is SBS_HORZ. 

The following example demonstrates the correct usage of the 
SCROLLBAR statement: 
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SCROLLBAR 999, 25, 30, 10, 100 



CONTROL 



Syntax CONTROL text, id, class, style, x, y, width, height 

This statement defines a user-defined control window. 

The text field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. 

The id field takes a unique integer value that identifies the control. 

The class field takes a predefined name, character string, or integer value 
that defines the class. This can be any one of the control classes; for a list 
of the control classes, see Table 8.2, "Control classes." If the value is a 
predefined name supplied by the application, it must be an ASCII string 
enclosed in double quotation marks. 

The style field takes a predefined name or integer value that specifies the 
style of the given control. The exact meaning of style depends on the class 
value. Tables 8.2, "Control classes," and 8.3, "Control styles," list the 
control classes and corresponding styles. 

The x and y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The horizontal units are 1 /4 of the 
dialog base width unit; the vertical units are 1/8 of the dialog base height 
unit. The current dialog base units are computed from the height and 
width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. The coordinates are relative to the 
origin of the dialog box. 

The width and height fields take integer values that specify the width and 
height of the control. The width units are 1 /4 of the dialog base width 
unit; the height units are 1/8 of the dialog base height unit. 



Comments 



Table 8.2 
Control classes 



The x, y, width, and height fields can use the addition operator (+) for 
relative positioning. For example, "15 + 6" can be used for the x field. 

Table 8.2 describes the six control classes: 

Class Description 

BUTTON A button control is a small rectangular child window that 

represents a "button" that the user can turn on or off by 
clicking it with the mouse. Button controls can be used alone or 
in groups, and can either be labeled or appear without text. 
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Table 8.2: Control classes (continued) 



COMBOBOX 



EDIT 



Button controls typically change appearance when the user 
clicks them. 

Combo-box controls consist of a selection field similar to an 
edit control plus a list box. The list box may be displayed at all 
times or may be dropped down when the user selects a "pop 
box" next to the selection field. 

Depending on the style of the combo box, the user can or 
cannot edit the contents of the selection field. If the list box is 
visible, typing characters into the selection box will cause the 
first list box entry which matches the characters typed to be 
highlighted. Conversely, selecting an item in the list box 
displays the selected text in the selection field. 
An edit control is a rectangular child window in which the 
user can enter text from the keyboard. The user selects the 
control, and gives it the input focus, by clicking the mouse 
inside it or pressing the TAB key. The user can enter text when 
the control displays a flashing caret. The mouse can be used to 
move the cursor and select characters to be replaced, or to 
position the cursor for inserting characters. The BACKSPACE key 
can be used to delete characters. 

Edit controls use the fixed-pitch font and display ANSI 
characters. They expand tab characters into as many space 
characters as are required to move the cursor to the next tab 
stop. Tab stops are assumed to be at every eighth character 
position. 

List-box controls consist of a list of character strings. The 
control is used whenever an application needs to present a list 
of names, such as filenames, that the user can view and select. 
The user can select a string by pointing to the string with the 
mouse and clicking a mouse button. When a string is selected, 
it is highlighted, and a notification message is passed to the 
parent window. A scroll bar can be used with a list-box control 
to scroll lists that are too long or too wide for the control 
window. 

A scroll-bar control is a rectangle that contains a scroll thumb 
and has direction arrows at both ends. The scroll bar sends a 
notification message to its parent whenever the user clicks the 
mouse in the control. The parent is responsible for updating 
the thumb position, if necessary. Scroll-bar controls have the 
same appearance and function as the scroll bars used in 
ordinary windows. But unlike scroll bars, scroll-bar controls 
can be positioned anywhere within a window and used 
whenever needed to provide scrolling input for a window. 
The scroll-bar class also includes size-box controls. A size-box 
control is a small rectangle that the user can expand to change 
the size of the window. 

Static controls are simple text fields, boxes, and rectangles that 
can be used to label, box, or separate other controls. Static 
controls take no input and provide no output. 



LISTBOX 



SCROLLBAR 



STATIC 
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Table 8.3 — — 
Control styles st V le 



Table 8.3 describes the control styles for each of the control classes: 



BUTTON class 



BS PUSHBUTTON 



BS DEFPUSHBUTTON 



BS_CHECKBOX 

BS_AUTOCHECKBOX 
BS RADIOBUTTON 



BS_AUTORADIOBUTTON 

BS_LEFTTEXT 

BS_3STATE 

BS_AUT03STATE 
BS_GROUPBOX 
BS OWNERDRAW 



Description 



A small elliptical button containing the given 
text. The control sends a message to its parent 
whenever the user clicks the mouse inside the 
rectangle. 

A small elliptical button with a bold border. 
This button represents the default user 
response. Any text is displayed within the 
button. Windows sends a message to the 
parent window when the user clicks the 
mouse in this button. 
A small rectangular button that can be 
checked; its border becomes bold when the 
user clicks the mouse in it. Any text appears to 
the right of the button. 
Identical to BS_CHECKBOX except that the 
button automatically toggles its state 
whenever the user clicks it. 
A small circular button whose border becomes 
bold when the user clicks the mouse in it. In 
addition, to make the border bold, Windows 
sends a message to the button's parent 
notifying it that a click occurred. On the next 
click, Windows makes the border normal 
again and sends another message. 
Identical to BS_RADIOBUTTON except that 
when the button is checked, the application is 
notified with BN_CLICKED, and all other 
radio buttons in the group are unchecked. 
Text appears on the left side of the radio 
button or check-box button. Use this style 
with BS_CHECKBOX, BS_3STATE, or 
BS_RADIOBUTTON styles. 
Identical to BS_CHECKBOX except that a 
button can be grayed as well as checked or 
unchecked. The grayed state is typically used 
to show that a check box has been disabled. 
Identical to BS_3STATE except that the button 
automatically toggles its state when the user 
clicks it. 

A rectangle into which other buttons are 
grouped. Any text is displayed in the 
rectangle's upper-left corner. 
An owner-draw button. The parent window is 
notified when the button is clicked. 
Notification includes a request to paint, invert, 
and disable the button. 
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Table 8.3: Control styles (continued) 



COMBOBOX class 



CBS SIMPLE 



CBS DROPDOWN 



CBS DROPDOWNLIST 



CBS OWNERDRAWFIXED 



CBS OWNERDRAWVARIABLE 



CBS AUTOHSCROLL 



CBS_SORT 

CBS HASSTRINGS 



CBS OEMCONVERT 



Displays the list box at all times. The current 

selection in the list box is displayed in the edit 

control. 

Is similar to CBS_SIMPLE, except that the list 

box is not displayed unless the user selects an 

icon next to the selection field. 

Is similar to CBS_DROPDOWN, except that 

the edit control is replaced by a static text item 

which displays the current selection in the list 

box. 

Specifies a fixed-height owner-draw combo 

box. The owner of the list box is responsible 

for drawing its contents; the items in the list 

box are all the same height. 

Specifies a variable-height owner-draw combo 

box. The owner of the list box is responsible 

for drawing its contents; the items in the list 

box can have different heights. 

Scrolls the text in the edit control to the right 

when the user types a character at the end of 

the line. If this style is not set, only text which 

fits within the rectangular boundary is 

allowed. 

Sorts strings entered into the list box. 

Specifies an owner-draw combo box that 

contains items consisting of strings. The 

combo box maintains the memory and 

pointers for the strings so that the application 

can use the LB_GETTEXT message to retrieve 

the text for a particular item. 

Text entered in the combo box edit control is 

converted from the ANSI character set to the 

OEM character set and then back to ANSI. 

This ensures proper character conversion 

when the application calls the AnsiToOem 

function to convert an ANSI string in the 

combo box to OEM characters. This style is 

most useful for combo boxes that contain 

filenames and applies only to combo boxes 

created with the CBS_SIMPLE or 

CBS_DROPDOWN styles. 



EDIT class 



ES_LEFT 
ES_CENTER 

ES RIGHT 



Flush-left text. 

Centered text. This style is valid in multiline 

edit controls only. 

Flush-right text. This style is valid in multiline 

edit controls only. 
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Table 8.3: Control styles (continued) 



ES_LOWERCASE 
ESJJPPERCASE 
ES PASSWORD 



ES MULTILINE 



ES_AUTOVSCROLL 
ES AUTOHSCROLL 



Lowercase edit control. An edit control with 
this style converts all characters to lowercase 
as they are typed into the edit control. 
Uppercase edit control. An edit control with 
this style converts all characters to uppercase 
as they are typed into the edit control. 
Password edit control. An edit control with 
this style displays all characters as an asterisk 
(*) as they are typed into the edit control. An 
application can use the 
EM_SETPASSWORDCHAR message to 
change the character that is displayed. 
Multiple-line edit control. (The default is 
single-line.) If the ES_AUTOVSCROLL style is 
specified, the edit control shows as many lines 
as possible and scrolls vertically when the 
user presses the ENTER key. (This is actually 
the carriage-return character, which the edit 
control expands to a carriagereturn/ line-feed 
combination. A line feed is not treated the 
same as a carriage return.) If 
ES_AUTOVSCROLL is not given, the edit 
control shows as many lines as possible and 
beeps if the user presses ENTER when no more 
lines can be displayed. 
If the ES_AUTOHSCROLL style is specified, 
the multiple-line edit control automatically 
scrolls horizontally when the caret goes past 
the right edge of the control. To start a new 
line, the user must press the ENTER key. If 
ES_AUTO-HSCROLL is not given, the control 
automatically wraps words to the beginning 
of the next line when necessary; a new line is 
also started if the user presses ENTER. The 
position of the wordwrap is determined by 
the window size. If the window size changes, 
the wordwrap position changes, and the text 
is redisplayed. 

Multiple-line edit controls can have scroll 
bars. An edit control with scroll bars processes 
its own scroll-bar messages. Edit controls 
without scroll bars scroll as described above, 
and process any scroll messages sent by the 
parent window. 

Text is automatically scrolled up one page 
when the user presses the ENTER key on the 
last line. 

Text is automatically scrolled to the right by 
10 characters when the user types a character 
at the end of the line. When the user presses 
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Table 8.3: Control styles (continued) 



ES NOHIDESEL 



ES OEMCONVERT 



the ENTER key, the control scrolls all text back 
to position 0. 

Normally, an edit control hides the selection 
when the control loses the input focus, and 
inverts the selection when the control receives 
the input focus. Specifying ES_NOHIDESEL 
overrides this default action. 
Text entered in the edit control is converted 
from the ANSI character set to the OEM 
character set and then back to ANSI. This 
ensures proper character conversion when the 
application calls the AnsiToOem function to 
convert an ANSI string in the edit control to 
OEM characters. This style is most useful for 
edit controls that contain filenames. 



LISTBOX class 



LBS_STANDARD 

LBS_EXTENDEDSEL 
LBS_HASSTRINGS 

LBS_NOTIFY 

LBS_MULTIPLESEL 

LBS_MULTICOLUMN 

LBS NOINTEGRALHEIGHT 



LBS_SORT 

LBS NOREDRAW 



Strings in the list box are sorted alphabetically 
and the parent window receives an input 
message whenever the user clicks or double- 
clicks a string. The list box contains borders on 
all sides. 

The user can select multiple items using the 
mouse with the SHIFT and /or the CONTROL key 
or special key combinations. 
An owner-draw list box contains items 
consisting of strings. The list box maintains 
the memory and pointers for the strings so the 
application can use the LB_GETTEXT message 
to retrieve the text for a particular item. 
The parent receives an input message 
whenever the user clicks or double-clicks a 
string. 

The string selection is toggled each time the 
user clicks or double-clicks the string. Any 
number of strings can be selected. 
The list box contains multiple columns. The 
list box can be scrolled horizontally. The 
LB_SETCOLUMNWIDTH message sets the 
width of the columns. 
The size of the list box is exactly the size 
specified by the application when it created 
the list box. Normally, Windows sizes a list 
box so that the list box does not display partial 
items. 

The strings in the list box are sorted 
alphabetically. 

The list-box display is not updated when 
changes are made. This style can be changed 
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Table 8.3: Control styles (continued) 



LBS OWNERDRAWFIXED 



LBS OWNERDRAWVARIABLE 



LBS USETABSTOPS 



LBS WANTKEYBOARDINPUT 



at any time by sending a WM_SETREDRAW 
message. 

The owner of the list box is responsible for 
drawing its contents; the items in the list box 
are all the same height. 
The owner of the list box is responsible for 
drawing its contents; the items in the list box 
are variable in height. 

The list box is able to recognize and expand 
tab characters when drawing its strings. The 
default tab positions are set at every 32 dialog 
units. (A dialog unit is a horizontal or vertical 
distance. One horizontal dialog unit is equal 
to 1 /4 of the current dialog base width unit. 
The dialog base units are computed from the 
height and width of the current system font. 
The GetDialogBaseUnits function returns the 
size of the dialog base units in pixels.) 
The owner of the list box receives 
WM_VKEYTOITEM or WM_CHARTOITEM 
messages whenever the user presses a key 
when the list box has input focus. This allows 
an application to perform special processing 
on the keyboard input. 



SCROLLBAR class 



SBS VERT 



SBS RIGHTALIGN 



SBS LEFTALIGN 



SBS HORZ 



SBS TOPALIGN 



Vertical scroll bar. If neither 
SBS_RIGHTALIGN nor SBS_LEFTALIGN is 
specified, the scroll bar has the height, width, 
and position given in the CreateWindow 
function. 

Used with SBS_VERT. The right edge of the 
scroll bar is aligned with the right edge of the 
rectangle specified by the x, y, width, and 
height values given in the CreateWindow 
function. The scroll bar has the default width 
for system scroll bars. 
Used with SBS_VERT. The left edge of the 
scroll bar is aligned with the left edge of the 
rectangle specified by the x, y, width, and 
height values given in the CreateWindow 
function. The scroll bar has the default width 
for system scroll bars. 
Horizontal scroll bar. If neither 
SBS_BOTTOMALIGN nor SBS_TOPALIGN is 
specified, the scroll bar has the height, width, 
and position given in the CreateWindow 
function. 

Used with SBS_HORZ. The top edge of the 
scroll bar is aligned with the top edge of the 
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Table 8.3: Control styles (continued) 



SBS BOTTOMALIGN 



SBS SIZEBOX 



rectangle specified by the x, y, width, and 
height values given in the CreateWindow 
function. The scroll bar has the default height 
for system scroll bars. 

Used with SBS_HORZ. The bottom edge of 
the scroll bar is aligned with the bottom edge 
of the rectangle specified by the x, y, width, 
and height values given in the CreateWindow 
function. The scroll bar has the default height 
for system scroll bars. 
_ Size box. If neither 

SBS_SIZEBOXBOTTOMRIGHT ALIGN nor 
SBS_SIZEBOXTOPLEFTALIGN is specified, 
the size box has the height, width, and 
position given in the CreateWindow function. 

SBS_SIZEBOXTOPLEFTALIGN Used with SBS_SIZEBOX. The top-left corner 

of the size box is aligned with the top-left 
corner of the rectangle specified by the x, y, 
width, and height values given in the 
CreateWindow function. The size box has the 
default size for system size boxes. 

SBS_SIZEBOXBOTTOMRIGHTALIGN 

Used with SBS_SIZEBOX. The bottom-right 
corner of the size box is aligned with the 
bottom-right corner of the rectangle specified 
by the x, y, width, and height values given in 
the CreateWindow function. The size box has 
the default size for system size boxes. 



STATIC class 



SS LEFT 



SS CENTER 



SS RIGHT 



SS LEFTNOWORDWRAP 



A simple rectangle displaying the given text 
flush left in the rectangle. The text is formatted 
before it is displayed. Words that would 
extend past the end of a line are automatically 
wrapped to the beginning of the next line. 
A simple rectangle displaying the given text 
centered in the rectangle. The text is formatted 
before it is displayed. Words that would 
extend past the end of a line are automatically 
wrapped to the beginning of the next line. 
A simple rectangle displaying the given text 
flush right in the rectangle. The text is 
formatted before it is displayed. Words that 
would extend past the end of a line are 
automatically wrapped to the beginning of the 
next line. 

A simple rectangle displaying the given text 
flush left in the rectangle. Tabs are expanded, 
but words are not wrapped. Text that extends 
past the end of a line is clipped. 
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Table 8.3: Control styles (continued) 



SS SIMPLE 



SS NOPREFIX 



SS ICON 



SS_BLACKRECT 

SS_GRAYRECT 

SS_WHITERECT 

SS_BLACKFRAME 

SS_GRAYFRAME 

SS_WHITEFRAME 

SS USERITEM 



Designates a simple rectangle and displays a 
single line of text flush-left in the rectangle. 
The line of text cannot be shortened or altered 
in any way. (The control's parent window or 
dialog box must not process the 
WM_CTLCOLOR message.) 
Unless this style is specified, windows will 
interpret any "&" characters in the control's 
text to be accelerator prefix characters. In this 
case, the "&" is removed and the next 
character in the string is underlined. If a static 
control is to contain text where this feature is 
not wanted, SS_NOPREFIX may be added. 
This static-control style may be included with 
any of the defined static controls. 
You can combine SS_NOPREFIX with other 
styles by using the bitwise OR operator. This is 
most often used when filenames or other 
strings that may contain an "&" need to be 
displayed in a static control in a dialog box. 
An icon displayed in the dialog box. The given 
text is the name of an icon (not a filename) 
defined elsewhere in the resource file. For the 
ICON statement, the width and height 
parameters in the CreateWindow function are 
ignored; the icon automatically sizes itself. 
A rectangle filled with the color used to draw 
window frames. This color is black in the 
default Windows color scheme. 
A rectangle filled with the color used to fill the 
screen background. This color is gray in the 
default Windows color scheme. 
A rectangle filled with the color used to fill 
window backgrounds. This color is white in 
the default Windows color scheme. 
Box with a frame drawn with the same color 
as window frames. This color is black in the 
default Windows color scheme. 
Box with a frame drawn with the same color 
as the screen background (desktop). This color 
is gray in the default Windows color scheme. 
Box with a frame drawn with the same color 
as window backgrounds. This color is white in 
the default Windows color scheme. 
User-defined item. 
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Directives 



The resource directives are special statements that define actions to be 
performed on the script file before it is compiled. The directives can assign 
values to names, include the contents of files, and control compilation of 
the script file. 

The resource directives are identical to the directives used in the C 
programming language. 



#include 
statement 

Syntax 



#include filename 

This directive copies the contents of the file specified by filename into your 
resource script before the Resource Compiler processes the script. It 
replaces the rcinclude directive of versions prior to Windows 3.0. 

The filename field is an ASCII string that specifies the DOS filename of the 
file to be included, using the same syntax as the C-language preprocessor 
#include directive. A forward slash (/) can be used instead of a backslash 
(for example, "root/sub"). If the filename has the .H or .C extension, only 
the preprocessor directives in the file are processed. Otherwise, this 
directive processes the entire contents of the file. 

The following example demonstrates the correct usage of the #include 
statement: 

iinclude "WINDOWS. H" 

PenSelect MENU 

BEGIN 

Menuitem "&Black pen", BLACK_PEN 
END 



#define 
statement 

Syntax 



#define name value 

This directive assigns the given value to name. All subsequent occurrences 
of name are replaced by value. 

The value field takes any integer value, character string, or line of text. 



Chapter 8, Resource script statements 



103 



The following example demonstrates the correct usage of the #define 
statement: 



tdefine 
idefine 



nonzero 
USERCLASS 



"MyControlClass" 



#undef 
statement 



Syntax #undef name 



This directive removes the current definition of name. All subsequent 
occurrences of name are processed without replacement. 

The following example demonstrates the correct usage of the #undef 
statement: 



#undef 
lundef 



nonzero 
USERCLASS 



#ifdef 
statement 



Syntax #ifdef name 



This directive carries out conditional compilation of the resource file by- 
checking the specified name. If name has been defined using a #def ine 
directive, #ifdef directs the Resource Compiler to continue with the 
statement immediately after #ifdef . If name has not been defined, #ifdef 
directs the compiler to skip all statements up to the next #endif directive. 

The following example demonstrates the correct usage of the#ifdef 
statement: 

fifdef Debug 

errbox BITMAP errbox.bmp 

#endif 
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#ifndef 
statement 



Syntax #ifndef name 



#if 
statement 



This directive carries out conditional compilation of the resource file by 
checking the specified name. If name has not been defined or if its 
definition has been removed using the #undef directive, #ifndef directs the 
Resource Compiler to continue processing statements up to the next 
#endif, #else, or #elif directive, and then to skip to the statement after 
#endif . If name is defined, #ifndef directs the compiler to skip to the next 
#endif, #else, or #elif directive. 

The following example demonstrates the correct usage of the #if ndef 
statement: 

iifndef Optimize 

errbox BITMAP errbox.bmp 

#endif 



Syntax #if constant-expression 

This directive carries out conditional compilation of the resource file by 
checking the specified constant-expression. If constant-expression is nonzero, 
#if directs the Resource Compiler to continue processing statements up to 
the next #endif, #else, or #elif directive, then skip to the statement after 
#endif . If constant-expression is zero, #if directs the compiler to skip to the 
next #endif, #else, or #elif directive. 

The constant-expression field specifies a defined name, an integer constant, 
or an expression consisting of names, integers, and arithmetical and 
relational operators. 

The following example demonstrates the correct usage of the #if 
statement: 

#if Version<3 

errbox BITMAP errbox.bmp 

#endif 
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#elif 
statement 



Syntax #eli£ constant-expression 

This directive marks an optional clause of a conditional compilation block 
defined by an #ifdef, #ifndef, or #if directive. The #elif directive carries out 
conditional compilation of the resource file by checking the specified 
constant-expression. If constant-expression is nonzero, #elif directs the 
Resource Compiler to continue processing statements up to the next 
#endif, #6186, or #elif directive, then skip to the statement after #endif. If 
constant-expression is zero, #elif directs the compiler to skip to the next 
#endif, #else, or #elif directive. Any number of #elif directives can be used 
in a conditional block. 

The constant-expression field specifies a defined name, an integer constant, 
or an expression consisting of names, integers, and arithmetical and 
relational operators. 

The following demonstrates the correct usage of the #elif statement: 

#if VersionO 

errbox BITMAP errbox.bmp 

lelif Version<7 

errbox BITMAP userbox.bmp 

#endif 



#else 
statement 



Syntax #else 



This directive marks an optional clause of a conditional compilation block 
defined by an #ifdef, #ifndef, or #if directive. The #else directive must be 
the last directive before #endif. 

The following example demonstrates the correct usage of the #else 
statement: 

tifdef Debug 

errbox BITMAP errbox.bmp 

lelse 

errbox BITMAP userbox.bmp 

#endif 
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#endif 
statement 



Syntax #endif 



This directive marks the end of a conditional compilation block defined by 
an #if or #ifdef directive. One #if or #endif is required for each #ifdef 
directive. 
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C H A 



File formats 



This chapter describes the file formats used to create, execute, and supply 
data to Microsoft Windows applications. These files include the following: 

a Bitmap files 
a Icon resource files 
d Cursor resource files 
p Clipboard files 
n Metafiles 



Bitmap file formats 



Windows version 3.0 bitmap files store a bitmap in a device-independent 
format which allows Windows to display the bitmap on any device. In 
this case, the term "device independent" means that the bitmap specifies 
pixel color in a form independent of the method used by any particular 
device to represent color. The assumed file extension of a Windows 
device-independent bitmap file is .BMP. 

Each bitmap file contains a BITMAPFILEHEADER data structure 
immediately followed by a single, device-independent bitmap (DIB) 
consisting of a BITMAPINFO data structure and an array of bytes that 
defines the bitmap bits. 

Windows version 3.0 also reads bitmap files in the format read by 
Microsoft OS/2 Presentation Manager version 1.2. These files consist of a 
BITMAPFILEHEADER data structure immediately followed by a 
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BITMAPCOREINFO data structure. Following this data structure is an 
array of bytes that defines the bitmap bits. 

See Chapter 7, "Data types and structures," for information on the 
BITMAPFILEHEADER, BITMAPCOREINFO and BITMAPINFO data 
structures. 



Icon resource file format 



An icon resource file (with the .ICO file extension) can be device 
independent both for color and resolution. 

Icon resource files can contain multiple device-independent bitmaps 
defining the icon image, one for each targeted display-device resolution. 
Windows detects the resolution of the current display and matches it 
against the x and y pixel-size values specified for each version of the 
image. If Windows determines that there is an exact match between an 
icon image and the current device, then it uses the matching image; 
otherwise, it selects the closest match and stretches the image to the 
proper size. 

If an icon resource file contains more than one image for a particular 
resolution, Windows uses the icon image that most closely matches the 
color capabilities of the current display device. If no image exists which 
exactly matches the device capabilities, Windows selects the image which 
has the greatest number of colors without exceeding the number of 
display-device colors. If all images exceed the color capabilities of the 
current display device, then Windows uses the icon image with the least 
number of colors. 

The icon resource file contains a header structure at the beginning of the 
file which identifies the type and number of icon images contained in the 
file. The following shows the format of this header: 



Field Type/Description 



icoReserved WORD Is reserved and must be set to 0. 

icoResourceType WORD Specifies the type of resource contained in the file. 

For an icon resource, this field must be 1. 
icoResourceCount WORD Specifies the number of images contained in the 

file. 

The resource directory follows this header. The resource directory consists 
of one or more arrays of resource descriptors. The icoResorceCount 
specifies the number of arrays. This list shows the format of the array: 
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Field 



Type/Description 



Width BYTE Specifies the width in pixels of this form of the icon 

image. Acceptable values are 16, 32, or 64. 
Height BYTE Specifies the height in pixels of this form of the icon 

image. Acceptable values are 16, 32, or 64. 
ColorCount BYTE Specifies the number of colors in this form of the 

icon image. Acceptable values are 2, 8, or 16. 
Reserved BYTE Reserved for future use. 

Reserved WORD Reserved for future use. 

Reserved WORD Reserved for future use. 

icoDIBSize DWORD Specifies in bytes the size of the pixel array for 

this form of the icon image. 
icoDIBOffset DWORD Specifies the offset in bytes from the beginning of 

the file to the device-independent bitmap for this form. 

Icons can be in color. To achieve transparency, the DIB for each icon will 
consist of two parts: 

1. A color bitmap which supplies the XOR mask for the icon. 

2. A monochrome bitmap which provides the AND mask that defines the 
transparent portion of the icon. 

The monochrome bitmap does not contain a DIB header, but instead 
immediately follows the color bitmap. It must have the same pixel height 
as the color bitmap. 



Cursor resource file format 



Like icon resource files, cursor resource files (with the .CUR file extension) 
may contain multiple images to match targeted display-device resolu- 
tions. In the case of cursors, Windows determines the best match for a 
particular display-device driver by examining the width and height of the 
cursor images. 

The cursor resource file contains a header structure at the beginning of the 
file which identifies the type and number of resources in the file. The 
following shows the format of this header: 



Field 



Type/Description 



curReserved 
curResourceType 

curResourceCount 



WORD Is reserved and must be set to 0. 

WORD Specifies the type of resource contained in the file. 

For a cursor resource, this field must be 2. 

WORD Specifies the number of resources contained in the 

file. 
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Table 9.1 
Bit mask results 



The resource directory follows this header. The resource directory consists 
of one or more arrays of resource descriptors. The curResorceCount 
specifies the number of arrays. The following shows the format of the 
array: 

Field Type/Description 

curWidth BYTE Specifies the width in pixels of this form of the 

cursor image. 
curHeight BYTE Specifies the height in pixels of this form of the 

cursor image. 
ColorCount BYTE Specifies the number of colors in this form of the 

icon image. Acceptable values are 2, 8, or 16. 
Reserved BYTE Is reserved and must be set to 0. 

curXHotspot WORD Specifies in pixels the horizontal position of the 

hotspot. 
curYHotspot WORD Specifies in pixels the vertical position of the 

hotspot. 
curDIBSize DWORD Specifies in bytes the size of the pixel array for 

this form of the cursor image. 
curDIBOffset DWORD Specifies in bytes the offset to the device- 

independent bitmap for this form. The offset is from the 

beginning of the file. 

Cursors are monochrome. The bitmap for a cursor consists of two parts; 
the first half is the XOR mask specifying the visible image, and the second 
half is the AND mask specifying the transparent portion of the cursor 
image. The two parts must be of equal width and height. By combining 
the values in corresponding mask bits, Windows determines whether a 
pixel is black, white, inverted, or transparent. 

Table 9.1 shows what values are necessary to produce the corresponding 
colors, inversions, or transparencies: 



Bit Value Bit Value Bit Value Bit Value 

AND mask 11 

XOR mask 10 1 

Resultant Pixel Black White Transparent Inverted 
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Clipboard file format 



The Windows clipboard saves and reads clipboard data in files with the 
.CLP extension. A clipboard-data file contains a value that identifies it as a 
clipboard-data file, one or more data structures defining the format, size, 
and location of the clipboard data, and one or more blocks of the actual 
data. 

The clipboard-data file begins with a header consisting of two fields. The 
following describes these fields: 

Field Type/Description 

Fileldentifier WORD Identifies the file as a clipboard-data file. This field 

must be set to CLPJD. 
FormatCount WORD Specifies the number of clipboard formats 

contained in the file. 

This header is followed by one or more data structures, each of which 
identifies the format, size, and offset of a block of clipboard data. The 
following shows the fields of this data structure: 

Field Type/Description 

FormatID WORD Specifies the clipboard-format ID of the clipboard 

data. See the description of the SetClipboardData function 
in Chapter 4, "Functions directory," in Reference, Volume 1, 
for information on clipboard formats. 

LenData DWORD Specifies in bytes the length of the clipboard data. 

Off Data DWORD Specifies in bytes the offset of the clipboard-data 

block. The offset is from the beginning of the file. 

Name Is a 79-character array that specifies the format name for a 

private clipboard format. 

The first block of clipboard data follows the last of these structures. For 
bitmaps and metafiles, the bits follow immediately after the bitmap 
header and the METAFILEPICT data structures. 



Metafile format 



A metafile consists of a collection of graphics device interface (GDI) 
function calls that create specific images on a device. Metafiles provide 
convenient storage for images that appear repeatedly in applications, and 
also allow you to use the clipboard to cut and paste images from one 
application to another. 
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Metafiles store images as a series of GDI function calls. After storing the 
function calls, applications play a metafile to generate an image on a 
device. 

When an object is created during playback, GDI adds the handle of the 
object to the first available entry in the metafile handle table. GDI clears 
the table entry corresponding to the object when it is deleted during 
playback, allowing the table entry to be reused when another object is 
created. 

Functions described in this section are discussed in greater detail in 
Chapter 4, "Functions directory," in Reference, Volume 1. 

The metafile itself consists of two parts: a header and a list of records. The 
header contains a description of the size (in words) of the metafile and the 
number of drawing objects it uses. The list of records contains the GDI 
functions. The drawing objects can be pens, brushes, or bitmaps. 



Metafile 
header 



The following structured list shows the format of the metafile header: 

struct { 
WORD mtType; 
WORD mtHeaderSize; 
WORD mtVersion; 
DWORD mtSize; 
WORD mtNoObjects; 
DWORD mtMaxRecord; 
WORD mtNoParameters; 



The metafile header contains the following fields: 



Field 



Description 



mtType 



mtHeaderSize 
mtVersion 

mtSize 
mtNoObjects 



Specifies whether the metafile is in memory or recorded in 
a disk file. It is one of these two values: 

Value Meaning 

1 Metafile is in memory 

2 Metafile is in a disk file 

Specifies the size in words of the metafile header. 

Specifies the Windows version number. The version 

number for Windows version 3.0 is 0x300. 

Specifies the size in words of the file. 

Specifies the maximum number of objects that exist in the 

metafile at the same time. 
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mtMaxRecord 
mtNoParameters 



Specifies the size in words of the largest record in the 

metafile. 

Is not used. 



Metafile 
records 



Table 9.2 

GDI functions and 

values 



A series of records follows the metafile header. Metafile records describe 
GDI functions. GDI stores most of the GDI functions that an application 
can use to create metafiles in similar, typical records. "Typical metafile 
record," later in this section, shows the format of the typical metafile 
record. Table 9.2, "GDI functions and values," lists the functions which 
GDI records in typical records, along with their respective function 
numbers. 

The remainder of the functions contain more complex structures in their 
records. "Function-specific records," later in this section, describes the 
records for these functions. 

In some cases, there are two versions of a metafile record. One version 
represents the record created by versions of Windows prior to version 3.0, 
while the second version represents the record created by Windows 
versions 3.0 and later. Windows 3.0 plays all metafile versions, but stores 
only 3.0 versions. Windows versions prior to 3.0 will not play metafiles 
recorded by Windows 3.0. 



Function 



Value 



Arc 0x0817 

Chord 0x0830 

Ellipse 0x0418 

ExcludeClipRect 0x0415 

FloodFill 0x0419 

IntersectClipRect 0x0416 

LineTo 0x0213 

MoveTo 0x0214 

OffsetClipRgn 0x0220 

OffsetViewportOrg 0x0211 

OffsetWindowOrg 0x020F 

PatBIt 0x061D 

Pie 0x081A 
RealizePalette (3.0 and later) 

0x0035 

Rectangle 0x041B 
ResizePalette (3.0 and later) 

0x0139 

RestoreDC 0x0127 

RoundRect 0x061C 

SaveDC OxOOlE 

ScaleViewportExt 0x0412 
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Table 9.2: GDI functions and values (continued) 



ScaleWindowExt 


0x0400 


SetBkColor 


0x0201 


SetBkMode 


0x0102 


SetMapMode 


0x0103 


SetMapperFlags 


0x0231 


SetPixel 


0x041F 


SetPolyFillMode 


0x0106 


SetROP2 


0x0104 


SetStretchBltMode 


0x0107 


SetTextAlign 


0x012E 


SetTextCharExtra 


0x0108 


SetTextColor 


0x0209 


SetTextJustification 


0x020A 


SetViewportExt 


0x020E 


SetViewportOrg 


0x020D 


SetWindowExt 


0x020C 


SetWindowOrg 


0x020B 



Typical metafile record 

The following structured list shows the format of a typical metafile record: 

struct! 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParmU; 
} 

A typical metafile record contains the following fields: 

Field Description 

rdSize Specifies the size in words of the record. 

rdFunction Specifies the function number. 

rdParm[ ] Is an array of words containing the function parameters, in the 

reverse order in which they are passed to the function. 



Function-specific records 

Some metafile records contain data structures in the parameter field. This 
section contains definitions for these records. 
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AnimatePalette record 3.0 

The AnimatePalette record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm[]; 
} 

This record contains the following fields: 



Field 



Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0436. 

rdParm[ ] Contains the following elements: 

Element Description 

start First entry to be animated, 

numentries Number of entries to be animated, 

entries PALETTEENTRY blocks. 



BitBIt record (prior to 3.0) 

The BitBIt record stored by Windows versions prior to 3.0 contains a 
device-dependent bitmap which may not be suitable for playback on all 
devices. The following is the format of this record: 

struct { 
DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 
} 

This record contains the following fields: 



Field 



Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0922 . 

rdParm[ ] Contains the following elements: 

Element Description 

raster op High word of the raster operation. 

SY The y-coordinate of the source origin. 

SX The x-coordinate of the source origin. 

DYE Destination y-extent. 

DXE Destination x-extent. 

DY The y-coordinate of destination origin. 

DX The x-coordinate of destination origin. 
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bm Width Width of bitmap (in pixels) 

bmHeight Height of bitmap (in raster lines) 

bmWidthBytes Number of bytes in each raster line. 

bmPlanes Number of color planes in the bitmap. 

bmBitsPixel Number of adjacent color bits, 

bits Actual device-dependent bitmap bits. 



BitBIt record 3.0 

The BitBIt record stored by Windows versions 3.0 and later contains a 
device-independent bitmap suitable for playback on any device. The 
following is the format of this record: 

struct { 
DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 
} 



This record contains the following fields: 



Field Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0940. 

rdParm[ ] Contains the following elements: 

Element Description 

raster op High word of the raster operation. 

SY The y-coordinate of the source origin. 

SX The x-coordinate of the source origin. 

DYE The y-extent of the destination. 

DXE The x-extent of the destination. 

DY The y-coordinate of destination origin. 

DX The x-coordinate of destination origin. 

Bitmaplnfo BITMAPINFO data structure. 

bits Actual device-independent bitmap bits. 



CreateBrushlndirect record 

The CreateBrushlndirect record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

L0GBRUSH rdParm; 
} 



This record contains the following fields: 
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Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x02FC. 

rdParm Specifies the logical brush. 



CreateFontlndirect record 

The CreateFontlndirect record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

LOGFONT rdParm; 
} 

This record contains the following fields: 

Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x02FB. 

rdParm Specifies the logical font. 

CreatePalette record 3.0 

The CreatePalette record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

LOGPALETTE rdParm; 
} 

This record contains the following fields: 

Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x00F7. 

rdParm Specifies the logical palette. 



CreatePattern Brush record (prior to 3.0) 

The CreatePatternBrush record stored by Windows versions prior to 3.0 
contains a device-dependent bitmap which may not be suitable for 
playback on all devices. The following is the format of this record: 
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struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParmt]; 
} 



This record contains the following fields: 



Field 



Description 



rdSize 
rdFunction 
rdParm[ ] 



Specifies the record size in words. 
Specifies the function number 0x01F9. 
Contains the following elements: 



Element 

bmWidth 
bmHeight 
bmWidthBytes 
bmPlanes 


Description 

Bitmap width. 
Bitmap height. 
Bytes per raster line. 
Number of color planes. 


bmBitsPixel 


Number of adjacent color bits that define 


bmBits 


a pixel. 

Pointer to bit values. 


bits 


Actual bits of pattern. 



CreatePatternBrush record 3.0 

The CreatePatternBrush record stored by Windows versions 3.0 and later 
contains a device-independent bitmap suitable for playback on all devices. 
The following is the format of this record: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm [ ] ; 
} 



This record contains the following fields: 



Field 



Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0142. 

rdParm[ ] Contains the following elements: 

Element Description 

type Bitmap type. This field may be either of these 

two values: 

■ BS_PATTERN— Brush is defined by a 
device-dependent bitmap through a call to 
the CreatePatternBrush function. 
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Usage 



Bitmaplnfo 
bits 



□ BS_DIBPATTERN— Brush is defined by a 
device-independent bitmap through a call to 
the CreateDIBPatternBrush function. 

Specifies whether the bmiColorsf ] field of the 
BITMAPINFO data structure contains explicit 
RGB values or indexes into the currently 
realized logical palette. This field must be one 
of the following values: 

□ DIB_RGB_COLORS— The color table 
contains literal RGB values. 

□ DIB_PAL_COLORS— The color table 
consists of an array of indexes into the 
currently realized logical palette. 

BITMAPINFO data structure. 

Actual device-independent bitmap bits. 



CreatePenlndirect record 

The format and field descriptions of the CreatePenlndirect record follow: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

LOGPEN rdParm; 
} 



Field 



Description 



rdSize 

rdFunction 

rdParm 



Specifies the record size in words. 
Specifies the function number 0x02FA. 
Specifies the logical pen. 



Create region record 

The format and field descriptions of the Create Region record follow: 

struct { 
DWORD rdSize; 
WORD rdFunction; 
WORD rdParm [] ; 



Field 



Description 



rdSize 
rdFunction 
rdParm[ ] 



Specifies the record size in words. 
Specifies the function number 0x06FF. 
Specifies the region to be created. 
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DeleteObject 3.0 

The DeleteObject record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm; 
} 

This record contains the following fields: 

Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number OxOlFO. 

rdParm Specifies the handle-table index of the object to be deleted. 

DrawText record 

The DrawText record has the following format: 

struct{ 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm[]; 
} 

This record contains the following fields: 

Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x062F. 

rdParm[ ] Contains the following elements: 

Element Description 

format Method of formatting. 

count Number of bytes in the string. 

rectangle Rectangular structure defining area where 

text is to be defined, 
string Byte array containing the string. The array 

is ((count + 1) »» 1) words long. 



Escape record 

The format and field descriptions of the Escape record follow: 

struct { 
DWORD rdSize; 
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WORD rdFunction; 
WORD rdParmf] ; 



Field 



Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0626. 

rdParmf ] Contains the following elements: 

Element Description 

escape number Number identifying individual escape, 

count Number of bytes of information, 

input data Variable length field. The field is 

((count+1)/ »» 1) words long. 



ExtTextOut record 

The ExtTextOut record has the following format: 

struct! 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm [ ] ; 
} 

This record contains the following fields: 



Field 



Description 



rdSize 
rdFunction 
rdParm[ ] 



Specifies the record size in words. 
Specifies the function number 0x0A32. 
Contains the following elements: 



Element 

y 

X 

count 

options 

rectangle 



string 
dxarray 



Description 

Logical y-value of string's starting point. 
Logical x-value of string's starting point. 
Length of the string. 
Rectangle type. 

RECT structure defining the ExtTextOut 
rectangle if options element is nonzero; 
nonexistent if options element equals zero 
Byte array containing the string. The array is 
((count + 1) »» 1) words long. 
Optional word array of intercharacter 
distances. 
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Polygon record 

The Polygon record has the following format: 



struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm[]; 
} 



This record contains the following fields: 



Field 



Description 



rdSize 
rdFunction 
rdParm[ ] 



Specifies the record size in words. 
Specifies the function number 0x0324. 
Contains the following elements: 



Element 

count 

list of points 



Description 

Number of points. 

List of individual points. 



PolyPolygon record 

The PolyPolygon record has the following format: 



struct { 




DWORD rdSize; 




WORD rdFunction; 


WORD rdParm[] 


»' 


This record contains the following fields: 


Field 


Description 


rdSize 
rdFunction 
rdParmf ] 


Specifies the record size in words. 
Specifies the function number 0x0538. 
Contains the following elements: 




Element Description 

count Total number of points. 

list of polygon counts List of number of points for each 

polygon, 
list of points List of individual points. 
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Polyline record 

The Polyline record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm [ ] ; 
} 

This record contains the following fields: 



Field Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0325. 

rdParm[ ] Contains the following elements: 



Element Description 

count Number of points. 

list of points List of individual points. 



SelectClipRegion 

The SelectClipRegion record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm; 
} 



This record contains the following fields: 



Field Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x012C. 

rdParm Specifies the handle-table index of the region being selected. 



SelectObject 

The SelectObject record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm; 
} 
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This record contains the following fields: 



Field 



Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x012D. 

rdParm Specifies the handle-table index of the object being selected. 



SelectPalette record 3.0 

The SelectPalette record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm; 
} 

This record contains the following fields: 

Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0234. 

rdParm Specifies the handle-table index of the logical palette being 

selected. 



SetDIBitsToDevice record 3.0 

The SetDIBitsToDevice record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm[]; 
} 

This record contains the following fields: 

Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0D33. 

rdParm[ ] Contains the following elements: 

Element Description 

wUsage Flag indicating whether the bitmap color 

table contains RGB values or indexes into 
the currently realized logical palette 

numscans Number of scan lines in the bitmap. 
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startscan First scan line in the bitmap. 

srcY The y-coordinate of the origin of the source 

in the bitmap. 
srcX The x-coordinate of the origin of the source 

in the bitmap. 
extY Height of the source in the bitmap. 

extX Width of the source in the bitmap. 

destY The y-coordinate of the origin of the 

destination rectangle. 
destX The x-coordinate of the origin of the 

destination rectangle. 
Bitmaplnfo BITMAPINFO data structure, 

bits Actual device-independent bitmap bits. 



SetPaletteEntries record 3.0 

The SetPaletteEntries record has the following format: 

struct { 
DWORD rdSize; 
WORD rdFunction; 
WORD rdParmU; 
} 

This record contains the following fields: 

Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0037. 

rdParm[ ] Contains the following elements: 

Element Description 

start First entry to be set in the palette, 

numentries Number of entries to be set in the palette, 

entries PALETTEENTRY blocks. 



StretchBIt record (prior to 3.0) 

The StretchBIt record stored by Windows versions prior to 3.0 contains a 
device-dependent bitmap which may not be suitable for playback on all 
devices. The following is the format of this record: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm [ ] ; 
} 

This record contains the following fields: 
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Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0B23. 

rdParm[ ] Contains the following elements: 

Element Description 

raster op Low word of the raster operation, 

raster op High word of the raster operation. 

SYE The y-extent of the source. 

SXE The x-extent of the source. 

SY The y-coordinate of the source origin. 

SX The ^-coordinate of the source origin. 

DYE The y-extent of the destination. 

DXE The x-extent of the destination. 

DY The y-coordinate of destination origin. 

DX The x-coordinate of destination origin, 

bm Width Width of the bitmap in pixels. 

bmHeight Height of the bitmap in raster lines. 

bmWidthBytes Number of bytes in each raster line. 

bmPlanes Number of color planes in the bitmap. 

bmBitsPixel Number of adjacent color bits, 

bits Actual bitmap bits. 



StretchBIt record 3.0 

The StretchBIt record stored by Windows versions 3.0 and later contains a 
device-independent bitmap suitable for playback on all devices. The 
following is the format of this record: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm [ ] ; 
} 

This record contains the following fields: 



Field 



Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0B41. 

rdParm[ ] Contains the following elements: 



Element 

raster op 

raster op 

SYE 

SXE 

SY 

SX 



Description 

Low word of the raster operation. 

High word of the raster operation. 

The y-extent of the source. 

The x-extent of the source. 

The y-coordinate of the source origin. 

The x-coordinate of the source origin. 



128 



Software development kit 



DYE The y-extent of the destination. 

DXE The x-extent of the destination. 

DY The y-coordinate of destination origin. 

DX The x-coordinate of destination origin. 

Bitmaplnfo BITMAPINFO data structure. 

bits Actual device-independent bitmap bits. 



StretchDIBits record 3.0 

The StretchDIBits record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm[] ; 
} 

This record contains the following fields: 
Field Description 



rdSize 
rdFunction 
rdParm[ ] 



Specifies the record size in words. 
Specifies the function number 0x0F43. 
Contains the following elements: 



Element 

dwRop 
wUsage 



srcYExt 
srcXExt 
srcY 

srcX 

dstYExt 
dstXExt 
dstY 

dstX 

Bitmaplnfo 
bits 



Description 

Raster operation to be performed. 

Flag indicating whether the bitmap color 

table contains RGB values or indexes into 

the currently realized logical palette 

Height of the source in the bitmap. 

Width of the source in the bitmap. 

The y-coordinate of the origin of the source 

in the bitmap. 

The x-coordinate of the origin of the source 

in the bitmap. 

Height of the destination rectangle. 

Width of the destination rectangle. 

The y-coordinate of the origin of the 

destination rectangle. 

The x-coordinate of the origin of the 

destination rectangle. 

BITMAPINFO data structure. 

Actual device-independent bitmap bits. 
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TextOut record 

The TextOut record has the following format: 

struct { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm[]; 
} 

This record contains the following fields: 



Field 



Description 



rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0521 . 

rdParm[ ] Contains the following elements: 

Element Description 

count The string's length. 

string The actual string. 

y-value Logical y-coordinate of string's starting point. 

x-value Logical ^-coordinate of string's starting point. 



Sample 

metafile 

program 

output 



This section shows the metafile created by a sample program. 

The following sample program creates a small metafile in which a purple 
rectangle with a green border is drawn, and the words "Hello People" are 
written in the rectangle. 

MakeAMetaFile(hDC) 

HDC hDC; 

{ 

HPEN hMetaGreenPen; 

HBRUSH hMetaVioletBrush; 

HDC hDCMeta; 

HANDLE hMeta; 

/* create the metafile with output going to the disk 

*/ 

hDCMeta = CreateMetaFile( (LPSTR) "sample. met") ; 

hMetaGreenPen = CreatePen(0, 0, (DWORD) OxOOOOFFOO); 
SelectObject (hDCMeta, hMetaGreenPen) ; 

hMetaVioletBrush = CreateSolidBrush( (DWORD) 

OxOOFFOOFF) ; 

SelectObject (hDCMeta, hMetaVioletBrush) ; 

Rectangle (hDCMeta, 0, 0, 150, 70); 
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TextOut(hDCMeta, 10, 10, (LPSTR) "Hello People", 12); 

/* we are done with the metafile */ 
hMeta = CloseMetaFile(hDCMeta); 

/* play the metafile that we just created */ 

PlayMetaFile(hDC, hMeta); 

} 

The resulting binary file SAMPLE.MET looks like this: 

0001 mtType... disk metafile 
0009 mtSize... 

0100 mt Vers ion 

0000 0036 mtSize 

0002 mtNoObjects 
0000 000C mtMaxrecord 
0000 mtNoParameters 

0000 0008 rdSize 

02FA rdFunction (CreatePen function call) 

0000 0000 0000 0000 FF00 rdParm (LOGPEN structure defining pen) 

0000 0004 rdSize 

012D rdFunction (SelectObject) 

0000 rdParm (index to object #0... the above pen) 

0000 0007 rdSize 

02FC rdFunction (CreateBrush) 

0000 00FF 00FF 0000 rdParm (LOGBRUSH structure defining the brush) 

0000 0004 rdSize 

012D rdFunction (SelectObject) 

0001 rdParm (index to object #1... the brush) 

0000 0007 rdSize 

041B rdFunction (Rectangle) 

0046 0096 0000 0000 rdParm (parameters sent to Rectangle. . .in reverse order) 

0000 000C rdSize 

0521 rdFunction (TextOut) 

rdParm 

000C count 

string 

48 65 6C 6C 6F 20 50 65 6F 70 6C 65 "Hello People" 

000A y-value 

000A x-value 
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Summary 



Windows files store information required to create Windows applications 
as well as data needed by the Windows system and Windows applications 
during execution. For more information on topics related to Windows 
files, see the following: 

Topic Reference 

Metafile functions Reference, Volume 1: Chapter 1, "Window 

manager interface functions," and Chapter 4, 
"Functions directory" 
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Module-definition statements 



This chapter describes the statements contained in the module-definition 
file that defines the application's contents and system requirements for the 
LINK program. LINK links compiled source files with Microsoft Windows 
and other libraries to create an executable Windows application. For 
information on running LINK, see Tools. 

The module-definition file contains one or more of the following module 
statements: 



Statement 


Description 


CODE 
DATA 
DESCRIPTION 


Code-segment attributes 
Data-segment attributes 
One-line description of the module 


EXETYPE 
EXPORTS 
HEAPSIZE 


.EXE header type (Windows or OS/2) 

Exported functions 

Size of local heap in bytes 


IMPORTS 
LIBRARY 
NAME 


Imported functions 
Dynamic-link library name 
Module name 


SEGMENTS 


Additional code segment 


STACKSIZE 


Size of local stack in bytes 


STUB 


Old-style executable 



This chapter describes these statements, their syntax, required and 
optional parameters, and usage. 
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CODE 



Syntax CODE [[FIXED I MOVEABLE]] [[DISCARDABLE]] [[\PRELOAD I 
LOADONCALL]] 

This statement defines the attributes of the standard code segment. The 
standard code segment is the application segment having the name 
_TEXT and belonging to the class CODE. In C applications, the standard 
data segment is created automatically if no specific segment name is 
included in the C-Compiler command line. 

The FIXED option, if included, means that the segment remains at a fixed 
memory location; the MOVEABLE option means that the segment can be 
moved, if necessary, in order to compact memory. 

The DISCARDABLE option, if included, means that the segment can be 
discarded if it is no longer needed. 

The PRELOAD option, if included, means that the segment is loaded 
when the module is first loaded; the LOADONCALL option means that the 
segment is loaded when it is called. The Resource Compiler may override 
this option. See Tools for more information. 

Comments There are no default attributes for code segments. The .DEF file should 
always explicitly define code-segment attributes. 

If conflicting options are included in the same statement, LINK uses the 
overriding option to determine the segment attributes. The following list 
shows which options override which: 

MOVEABLE overrides FIXED. 

PRELOAD overrides LOADONCALL. 

Example code moveable loadoncall 

In this example, the loader forces all fixed and moveable (but not 
discardable) code segments to be loaded. Libraries cannot have code that 
is moveable but not discardable. 



DATA 



Syntax Data [[NONE I SINGLE I MULTIPLE]] [[FIXED I MOVEABLE]] 

This statement defines the attributes of the standard data segment. The 
standard data segment is all application segments belonging to the group 
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DATA 



DGROUP and the class DATA. In C applications, the standard data 
segment is created automatically. The data is always preloaded. 

The NONE option, if included, means that there is no data segment. To be 
effective, this option should be the only attribute of the segment. This 
option is available only for libraries. 

The SINGLE option, if included, means that a single segment is shared by 
all instances of the module, and is valid only for libraries. 
The MULTIPLE option means that one segment exists for each instance, 
and is only valid for applications. 

NONE, SINGLE, and MULTIPLE are mutually exclusive. 

The FIXED option, if included, means that the segment remains at a fixed 
memory location. The MOVEABLE option means that the segment can be 
moved if necessary, in order to compact memory. 

Comments There are no default attributes for data segments. The .DEF file should 
always explicitly define data-segment attributes. 

Data segments are always preloaded. 

If conflicting options are included in the same statement, LINK uses the 
overriding option to determine the segment attributes. The following list 
shows which options override which: 

MULTIPLE overrides NONE. 

SINGLE overrides NONE. 

MOVEABLE overrides FIXED. 

Example data moveable single 

This example tells LINK that this module has a single, moveable data 
segment. 



DESCRIPTION 



Syntax DESCRIPTION 'text' 

This statement inserts text into the application's module. It is useful for 
embedding source-control or copyright information 



Parameters text 



Specifies one or more ASCII characters. The string must be 
enclosed in single quotation marks. 
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Example DESCRIPTION 'Microsoft Windows Template Application' 

This example embeds the text "Microsoft Windows Template Application" 
in the application module. 



EXETYPE 



Syntax EXETYPE headertype 

This statement specifies the default executable-file (.EXE) header type 
(Windows or OS/2). It is required for every Windows application. 



Parameters headertype 



Determines the header type. When linking an application 
intended for the Windows environment, you must set this 
parameter to the value "WINDOWS". For an MS OS/2 
application, set this parameter to the value "OS/2". 



Example exetype windows 



EXPORTS 



Syntax EXPORTS exportname [[ordinal-option]] [[\res-option]] [[data-option]] 
[[parameter-option]] 

This statement defines the names and attributes of the functions to be 
exported to other applications. The EXPORTS key word marks the 
beginning of the definitions. It can be followed by any number of export 
definitions, each on a separate line. 

Parameters exportname Specifies one or more ASCII characters that define the 

function name. It has the following form: 

<entryname>=[[internalname]] 

where the entryname parameter specifies the name to be used 
by other applications to access the exported function, and 
internalname is an optional parameter that defines the actual 
name of the function if entryname is not the actual name. 

ordinal-option Defines the function's ordinal value. It has the following 
form: 

©ordinal 
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res-option 



data-option 



EXPORTS 



where ordinal takes an integer value that specifies the 
function's ordinal value. The ordinal value defines the 
location of the function's name in the application's string 
table. (When exporting functions from libraries, it is better to 
use an ordinal rather than a name; using ordinals conserves 
space.) 

Is the optional key word RESIDENTNAME, which specifies 
that the function's name must be resident at all times. 

Is the optional key word NODATA, which specifies that the 
function is not bound to a specific data segment. When 
invoked, the function uses the current data segment. 



parameter-option 

Is an optional integer value that specifies the number of 
words the function expects to be passed as parameters. 



Example 



EXPORTS 



SampleRead=read2bin @1 
Stringln=strl @2 4 
CharTest NODATA 



This example exports the functions SampleRead, Stringln and CharTest so 
that other applications, or Windows itself, can call them. 



HEAPSIZE 



Syntax HEAPSIZE bytes 

This statement defines the number of bytes needed by the application for 
its local heap. An application uses the local heap whenever it allocates 
local memory 

The default heap size is zero. The minimum size is 256 bytes. For an 
application, the size of the local heap must be at least large enough to hold 
the current environment. 



Parameters bytes 



Is an integer value that specifies the heap size in bytes. It 
must not exceed 65,536 (the size of a single physical 
segment). 



Example heapsize 4096 

This example sets the size of the application's local heap to 4096 bytes. 
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IMPORTS 



Syntax 



IMPORTS [[internal-option]] modulename [[entry-option]] 

This statement defines the names and attributes of the functions to be 
imported from dynamic-link libraries. The IMPORTS key word marks the 
beginning of the definitions. It can be followed by any number of import 
definitions, each on a separate line. 



Parameters internal-option 



Example 



Specifies the name that the application will use to call the 
function. It has the following form: 

internal-name= 

where internal-name is one or more ASCII characters. This 
name must be unique. 

modulename Specifies one or more uppercase ASCII characters that define 
the name of the executable module that contains the 
function. The module name must match the name of the 
executable file. For example, an application with the 
executable file SAMPLE.DLL has the module name 
"SAMPLE". The executable file must be named with the 
.DLL extension. 

entry-option Specifies the function to be imported. It can be one of the 
following: 

.entryname 

.entryordinal 

where entryname is the actual name of the function, and 
entryordinal is the ordinal value of the function. 

IMPORTS 

Sample. SampleRead 
write2hex=Sample . SampleWrite 
Read.l 

Instead of listing imported DLL functions in the IMPORTS statement, you 
can specify an "import library" for the DLL in your application's LINK 
command line. It also saves space to import by ordinal. 
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LIBRARY 



Syntax LIBRARY libraryname 

This statement defines the name of a library module. Library modules are 
resource modules that contain code, data, and other resources but are not 
intended to be executed as an independent program. Like an application's 
module name, a library's module name must match the name of the 
executable file. For example, the library USER.EXE has the module name 
"USER". 

Parameters libraryname Specifies one or more ASCII characters that define the name 

of the library module. 

Comments The start address of the library module is determined by the library's 
object files; it is an internally defined function. 

The libraryname parameter is optional. If the parameter is not included, 
LINK uses the filename part of the executable file (that is, the name with 
the extension removed). 

If the .DEF file includes neither a NAME nor a LIBRARY statement, LINK 
assumes a NAME statement without a modulename parameter is desired. 

Example LIBRARY utilities 

This example gives a library the module name "Utilities." 



NAME 



Syntax NAME modulename 

This statement defines the name of the application's executable module. 
The module name identifies the module when exporting functions. 

Parameters modulename Specifies one or more uppercase ASCII characters that define 

the name of the executable module. The module name must 
match the name of the executable file. For example, an 
application with the executable file SAMPLE.EXE has the 
module name "SAMPLE". Do not use OS/2 system library 
names. Examples of these names are DOSCALLS, 
VIOCALLS, and MOUCALLS. 

Comments The modulename parameter is optional. If the parameter is not included, 
LINK assumes that the module name matches the the filename of the 
executable file. For example, if you do not specify a module name and the 
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executable file is named MYAPP.EXE, LINK assumes that the module 
name is "MYAPP". 

If the .DEF file includes neither a NAME nor a LIBRARY statement, LINK 
assumes a NAME statement without a modulename parameter is desired. 

Example NAME Calendar 

This example gives an application the module name "Calendar". 



SEGMENTS 



Syntax SEGMENTS segmentname [ [CLASS 'class-name'] ] [ [minalloc] ] \ 
[[FIXED I MOVEABLE]] 

[[DISCARDABLE]] [[SHARED I NONSHARED]] [[PRELOAD I 
LOADONCALL]] 

This statement defines the segment attributes of additional code and data 
segments. 

The FIXED option, if included, means that the segment remains at a fixed 
memory location. The MOVEABLE option means that the segment can be 
moved if necessary, in order to compact memory. 

The DISCARDABLE option, if included, means that the segment can be 
discarded if it is no longer needed. 

The PRELOAD option, if included, means that the segment is loaded 
immediately The LOADONCALL option means that the segment is loaded 
when it is accessed or called. The Resource Compiler may override this 
option. See Tools for more information. 

Parameters segmentname Specifies a character string that names the new segment. It 

can be any name, including the standard segment names 
_TEXT and _DATA, which represent the standard code and 
data segments. 

class-name Is an optional key word that specifies the class name of the 
specified segment. If no class name is specified, LINK uses 
the class name CODE by default. 

minalloc Is an optional integer value that specifies the minimum 

allocation size for the segment. 

Comments There are no default attributes for additional segments. The .DEF file 
should always explicitly define the attributes of additional segments. 
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SEGMENTS 



If conflicting options are included in the same statement, LINK uses the 
overriding option to determine the segment attributes. The following list 
shows which options override which: 

MOVEABLE overrides FIXED. 

PRELOAD overrides LOADONCALL. 

Example segments 

_TEXT FIXED 

_INIT PRELOAD DISCARDABLE 
RES CLASS 'DATA' PRELOAD DISCARDABLE 



STACKSIZE 



Syntax STACKSIZE bytes 

This statement defines the number of bytes needed by the application for 
its local stack. An application uses the local stack whenever it makes 
function calls. 

The default stack size is zero if the application makes no function calls. If 
your application does make function calls and you specify a stack size 
smaller than 5K bytes, Windows automatically sets the stack size to 5K 
bytes. 

Parameters bytes Is an integer value that specifies the stack size in bytes. 

Comments Do not use the STACKSIZE statement for dynamic-link libraries. 

Example stacksize 6144 

This example sets the size of an application's stack to 6144 bytes. 



STUB 



Syntax STUB "filename' 



This statement appends the old-style executable file specified by filename 
to the beginning of the module. The executable stub should display a 
warning message and terminate if the user attempts to execute the 
module without having loaded Windows. The default file WINSTUB.EXE 
can be used if no other actions are required. 
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Parameters filename Specifies the name of the old-style executable file that will be 

appended to the module. The name must have the DOS 
filename format. 

Comments If the file named by filename is not in the current directory, LINK searches 
for the file in the directories specified by the user's PATH environment 
variable. 

Example stub 'WINSTub.exe' 

This example specifies the executable file WINSTUB.EXE as the 
application's stub. If a user tries to run this application in the DOS 
environment, rather than with Windows, the program WINSTUB.EXE 
starts instead. 
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Binary and ternary raster-operation 

codes 



This chapter lists and describes the binary and ternary raster operations 
used by the graphics device interface (GDI). A binary raster operation 
uses two operands: a pen and a destination bitmap. A ternary raster 
operation uses three operands: a source bitmap, a brush, and a destination 
bitmap. Both binary and ternary raster operations use Boolean operators. 

Binary raster operations 

This section lists the binary raster-operation codes used by the GetROP2 
and SetROP2 functions. Raster-operation codes define how GDI combines 
the bits from the selected pen with the bits in the destination bitmap. 

Each raster-operation code represents a Boolean operation in which the 
selected pen and the destination bitmap are combined. There are two 
operands used in these operations: 

n D Destination bitmap 
n P Selected pen 

The Boolean operators used in these operations are as follows: 

□ a Bitwise AND 

b n Bitwise NOT (inverse) 

b o Bitwise OR 

b x Bitwise Exclusive OR (XOR) 
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Table 11.1 
Operation indexes 
for DPo and DPan 



All Boolean operations are presented in reverse Polish notation. For 
example, the following operation replaces the destination with a 
combination of the pen and the selected brush: 

DPo 

Each raster-operation code is a 32-bit integer value whose high-order 
word is a Boolean operation index and whose low-order word is the 
operation code. The 16-bit operation index is a zero-extended 8-bit value 
that represents the result of the Boolean operation on predefined pen and 
destination values. For example, the operation indexes for the DPo and 
DPan operations are shown in Table 11.1: 



p 


D 


PSo 


DPSoo 











1 





1 


1 


1 


1 





1 


1 


1 


1 


1 






The following list outlines the drawing modes and the Boolean operations 
that they represent: 



Raster operation 



Boolean operation 



R2 BLACK 





R2 COPYPEN 


P 


R2 MASKNOTPEN 


DPna 


R2 MASKPEN 


DPa 


R2 MASKPENNOT 


PDna 


R2 MERGENOTPEN 


DPno 


R2 MERGEPEN 


DPo 


R2 MERGEPENNOT 


PDno 


R2 NOP 


D 


R2 NOT 


Dn 


R2 NOTCOPYPEN 


Pn 


R2 NOTMASKPEN 


DPan 


R2 NOTMERGEPEN 


DPon 


R2 NOTXORPEN 


DPxn 


R2 WHITE 


1 


R2 XORPEN 


DPx 



When a monochrome device is used, GDI maps the value to black and 
the value 1 to white. Given an application that attempts to draw with a 
black pen on a white destination by using the available binary raster 
operations, the following results will occur: 
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Raster operation 



Result 



R2_BLACK 

R2_COPYPEN 

R2_MASKNOTPEN 

R2_MASKPEN 

R2_MASKPENNOT 

R2_MERGENOTPEN 

R2_MERGEPEN 

R2_MERGEPENNOT 

Pv2_NOP 

R2_NOT 

R2_NOTCOPYPEN 

R2_NOTMASKPEN 

R2_NOTMERGEPEN 

R2_NOTXORPEN 

R2_WHITE 

R2 XORPEN 



Visible black line 
Visible black line 
No visible line 
Visible black line 
Visible black line 
No visible line 
Visible black line 
Visible black line 
No visible line 
Visible black line 
No visible line 
No visible line 
Visible black line 
Visible black line 
No visible line 
No visible line 



When a color device is used, GDI uses RGB values to represent the colors 
of the pen and the destination. An RGB color value is a long integer that 
contains a red, a green, and a blue color field, each specifying the intensity 
of the given color. Intensities range from to 255. The values are packed 
in the three low-order bytes of the long integer. The color of a pen is 
always a solid color, but the color of the destination may be a mixture of 
any two or three colors. Given an application that attempts to draw with a 
white pen on a blue destination by using the available binary raster 
operations, the following results will occur: 



Raster Operation 



Result 



R2_BLACK 

R2_COPYPEN 

R2_MASKNOTPEN 

R2_MASKPEN 

R2_iVIASKPENNOT 

R2_MERGENOTPEN 

R2_MERGEPEN 

R2_MERGEPENNOT 

R2_NOP 

R2_NOT 

R2_NOTCOPYPEN 

R2_NOTMASKPEN 

R2_NOTMERGEPEN 

R2_NOTXORPEN 

R2_WHITE 

R2 XORPEN 



Visible black line 
Visible white line 
Visible black line 
Invisible blue line 
Visible red /green line 
Invisible blue line 
Visible white line 
Visible white line 
Invisible blue line 
Visible red /green line 
Visible black line 
Visible red/green line 
Visible black line 
Invisible blue line 
Visible white line 
Visible red /green line 
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Ternary raster operations 



Table 11.2 
Operation Indexes 
for PSo and DPSoo 



This section lists the ternary raster-operation codes used by the BitBIt, 
PatBIt, and Stretch Bit functions. Ternary raster-operation codes define 
how GDI combines the bits in a source bitmap with the bits in the 
destination bitmap. 

Each raster-operation code represents a Boolean operation in which the 
source, the selected brush, and the destination bitmap are combined. 
There are three operands used in these operations: 

■ D Destination bitmap 

■ P Selected brush (also called pattern) 

■ S Source bitmap 

The Boolean operators used in these operations are as follows: 

■ a Bitwise AND 

■ n Bitwise NOT (inverse) 

■ o Bitwise OR 

■ x Bitwise Exclusive OR (XOR) 

All Boolean operations are presented in reverse Polish notation. For 
example, the following operation replaces the destination with a 
combination of the source and brush: 

PSo 

The following operation combines the source and brush with the 
destination (there are alternate spellings of the same function, so although 
a particular spelling may not be in the list, an equivalent form will be): 

DPSoo 

Each raster-operation code is a 32-bit integer value whose high-order 
word is a Boolean operation index and whose low-order word is the 
operation code. The 16-bit operation index is a zero-extended, 8-bit value 
that represents the result of the Boolean operation on predefined brush, 
source, and destination values. For example, the operation indexes for the 
PSo and DPSoo operations are shown in Table 11.2: 



PSo 



DPSoo 
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Table 1 1 .2: Operation Indexes for PSo and DPSoo (continued) 



1 


1 


1 


1 


1 1 





1 


1 


1 1 


1 


1 


1 


Operation index: 




OOFC 


OOFE 



For more 

information about 

RGB values, see the 

RGB structure in 

Chapter 7, "Data 

types and 

structures. " 



In this case, PSo has the operation index OOFC (read from the bottom up); 
DPSoo has the operation index OOFE. These values define the location of 
the corresponding raster-operation codes, as shown in Table 11.1, 
"Operation indexes for DPo and DPan." The PSo operation is in line 252 
(FCh) of the table; DPSoo is in line 254 (FEh). 

The most commonly used raster operations have been given special 
names in the Windows include file, windows.h. You should use these 
names whenever possible in your applications. 

When the source and destination are monochrome, a bit value of zero 
represents a black pixel and a bit value of 1 represents a white pixel. 
When the source and the destination are color, those colors are 
represented with RGB values. 

Table 11.3 lists the raster-operation codes: 



Table 1 1 .3 

Raster-operation 

codes 



Boolean 
Function 
in Hex, Hex 



00 

01 

02 

03 

04 

05 

06 

07 

08 

09 

0A 

0B 

0C 

0D 

0E 

OF 

10 

11 

12 

13 

14 

15 



Hex 
ROP 



Boolean 
Function 
in Reverse Polish 



Common 
Name 



00000042 





BLACKNESS 


00010289 


DPSoon 


- 


00020C89 


DPSona 


- 


000300AA 


PSon 


- 


00040C88 


SDPona 


- 


000500A9 


DPon 


- 


00060865 


PDSxnon 


- 


000702C5 


PDSaon 


- 


00080F08 


SDPnaa 


- 


00090245 


PDSxon 


- 


000A0329 


DPna 


- 


000B0B2A 


PSDnaon 


- 


000C0324 


SPna 


- 


000D0B25 


PDSnaon 


- 


000E08A5 


PDSonon 


- 


000F0001 


Pn 


- 


00100C85 


PDSona 


- 


001100A6 


DSon 


NOTSRCERASE 


00120868 


SDPxnon 


- 


001302C8 


SDPaon 


- 


00140869 


DPSxnon 


- 


001502C9 


DPSaon 


- 
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16 

17 

18 

19 

1A 

IB 

1C 

ID 

IE 

IF 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

2A 

2B 

2C 

2D 

2E 

2F 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

3A 

3B 

3C 

3D 

3E 

3F 

40 

41 

42 

43 

44 

45 

46 

47 

48 



00165CCA 

00171D54 

00180D59 

00191CC8 

001A06C5 

001B0768 

001C06CA 

001D0766 

001E01A5 

001F0385 

00200F09 

00210248 

00220326 

00230B24 

00240D55 

00251CC5 

002606C8 

00271868 

00280369 

002916CA 

002A0CC9 

002B1D58 

002C0784 

002D060A 

002E064A 

002F0E2A 

0030032A 

00310B28 

00320688 

00330008 

003406C4 

00351864 

003601A8 

00370388 

0038078A 

00390604 

003A0644 

003B0E24 

003C004A 

003D18A4 

003E1B24 

003F00EA 

00400F0A 

00410249 

00420D5D 

00431CC4 

00440328 

00450B29 

004606C6 

0047076A 

00480368 



PSDPSanaxx 

SSPxDSxaxn 

SPxPDxa 

SDPSanaxn 

PDSPaox 

SDPSxaxn 

PSDPaox 

DSPDxaxn 

PDSox 

PDSoan 

DPSnaa 

SDPxon 

DSna 

SPDnaon 

SPxDSxa 

PDSPanaxn 

SDPSaox 

SDPSxnox 

DPSxa 

PSDPSaoxxn 

DPSana 

SSPxPDxaxn 

SPDSoax 

PSDnox 

PSDPxox 

PSDnoan 

PSna 

SDPnaon 

SDPSoox 

Sn 

SPDSaox 

SPDSxnox 

SDPox 

SDPoan 

PSDPoax 

SPDnox 

SPDSxox 

SPDnoan 

PSx 

SPDSonox 

SPDSnaox 

PSan 

PSDnaa 

DPSxon 

SDxPDxa 

SPDSanaxn 

SDna 

DPSnaon 

DSPDaox 

PSDPxaxn 

SDPxa 



NOTSRCCOPY 



SRCERASE 
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Table 1 1 .3: Raster-operation codes (continued) 



49 

4A 

4B 

4C 

4D 

4E 

4F 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

5A 

5B 

5C 

5D 

5E 

5F 

60 

61 

62 

63 

64 

65 

66 

67 

68 

69 

6A 

6B 

6C 

6D 

6E 

6F 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

7A 

7B 



004916C5 

004A0789 

004B0605 

004C0CC8 

004D1954 

004E0645 

004F0E25 

00500325 

00510B26 

005206C9 

00530764 

005408A9 

00550009 

005601A9 

00570389 

00580785 

00590609 

005A0049 

005B18A9 

005C0649 

005D0E29 

005E1B29 

005F00E9 

00600365 

006116C6 

00620786 

00630608 

00640788 

00650606 

00660046 

0G6718A8 

006858A6 

00690145 

006A01E9 

006B178A 

006C01E8 

006D1785 

006E1E28 

006F0C65 

00700CC5 

00711D5C 

00720648 

00730E28 

00740646 

00750E26 

00761B28 

007700E6 

007801E5 

00791786 

007A1E29 

007B0C68 



PDSPDaoxxn 

DPSDoax 

PDSnox 

SDPana 

SSPxDSxoxn 

PDSPxox 

PDSnoan 

PDna 

DSPnaon 

DPSDaox 

SPDSxaxn 

DPSonon 

Dn 

DPSox 

DPSoan 

PDSPoax 

DPSnox 

DPx 

DPSDonox 

DPSDxox 

DPSnoan 

DPSDnaox 

DPan 

PDSxa 

DSPDSaoxxn 

DSPDoax 

SDPnox 

SDPSoax 

DSPnox 

DSx 

SDPSonox 

DSPDSonoxxn 

PDSxxn 

DPSax 

PSDPSoaxxn 

SDPax 

PDSPDoaxxn 

SDPSnoax 

PDSxnan 

PDSana 

SSDxPDxaxn 

SDPSxox 

SDPnoan 

DSPDxox 

DSPnoan 

SDPSnaox 

DSan 

PDSax 

DSPDSoaxxn 

DPSDnoax 

SDPxnan 



DSTINVERT 



PATINVERT 



SRCINVERT 
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7C 

7D 

7E 

7F 

80 

81 

82 

83 

84 

85 

86 

87 

88 

89 

8A 

8B 

8C 

8D 

8E 

8F 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 

9A 

9B 

9C 

9D 

9E 

9F 

A0 

Al 

A2 

A3 

A4 

A5 

A6 

A7 

A8 

A9 

AA 

AB 

AC 

AD 

AE 



007C1E24 

007D0C69 

007E0955 

007F03C9 

008003E9 

00810975 

00820C49 

00831E04 

00840C48 

00851E05 

008617A6 

008701C5 

008800C6 

00891B08 

008A0E06 

008B0666 

008C0E08 

008D0668 

008E1D7C 

008F0CE5 

00900C45 

00911E08 

009217A9 

009301C4 

009417AA 

009501C9 

00960169 

0097588A 

00981888 

00990066 

009A0709 

009B07A8 

009C0704 

009D07A6 

009E16E6 

009F0345 

00A000C9 

00A11B05 

00A20E09 

00A30669 

00A41885 

00A50065 

00A60706 

00A707A5 

00A803A9 

00A90189 

00AA0029 

00AB0889 

00AC0744 

00AD06E9 

00AE0B06 



SPDSnoax 

DPSxnan 

SPxDSxo 

DPSaan 

DPSaa 

SPxDSxon 

DPSxna 

SPDSnoaxn 

SDPxna 

PDSPnoaxn 

DSPDSoaxx 

PDSaxn 

DSa 

SDPSnaoxn 

DSPnoa 

DSPDxoxn 

SDPnoa 

SDPSxoxn 

SSDxPDxax 

PDSanan 

PDSxna 

SDPSnoaxn 

DPSDPoaxx 

SPDaxn 

PSDPSoaxx 

DPSaxn 

DPSxx 

PSDPSonoxx 

SDPSonoxn 

DSxn 

DPSnax 

SDPSoaxn 

SPDnax 

DSPDoaxn 

DSPDSaoxx 

PDSxan 

DPa 

PDSPnaoxn 

DPSnoa 

DPSDxoxn 

PDSPonoxn 

PDxn 

DSPnax 

PDSPoaxn 

DPSoa 

DPSoxn 

D 

DPSono 

SPDSxax 

DPSDaoxn 

DSPnao 



SRCAND 
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Table 1 1 .3: Raster-operation codes (continued) 



AF 

BO 

Bl 

B2 

B3 

B4 

B5 

B6 

B7 

B8 

B9 

BA 

BB 

BC 

BD 

BE 

BF 

CO 

CI 

C2 

C3 

C4 

C5 

C6 

C7 

C8 

C9 

CA 

CB 

CC 

CD 

CE 

CF 

DO 

Dl 

D2 

D3 

D4 

D5 

D6 

D7 

D8 

D9 

DA 

DB 

DC 

DD 

DE 

DF 

EO 

El 



00AF0229 


DPno 


- 


00B00E05 


PDSnoa 


- 


00B10665 


PDSPxoxn 


- 


00B21974 


SSPxDSxox 


- 


00B30CE8 


SDPanan 


- 


00B4070A 


PSDnax 


- 


00B507A9 


DPSDoaxn 


- 


00B616E9 


DPSDPaoxx 


- 


00B70348 


SDPxan 


- 


00B8074A 


PSDPxax 


- 


00B906E6 


DSPDaoxn 


- 


00BA0B09 


DPSnao 


- 


00BB0226 


DSno 


MERGEPAINT 


00BC1CE4 


SPDSanax 


- 


00BD0D7D 


SDxPDxan 


- 


00BE0269 


DPSxo 


- 


00BF08C9 


DPSano 


- 


00C000CA 


PSa 


MERGECOPY 


00C11B04 


SPDSnaoxn 


- 


00C21884 


SPDSonoxn 


- 


00C3006A 


PSxn 


- 


00C40E04 


SPDnoa 


- 


00C50664 


SPDSxoxn 


- 


00C60708 


SDPnax 


- 


00C707AA 


PSDPoaxn 


- 


00C803A8 


SDPoa 


- 


00C90184 


SPDoxn 


- 


00CA0749 


DPSDxax 


- 


00CB06E4 


SPDSaoxn 


- 


00CC0020 


S 


SRCCOPY 


00CD0888 


SDPono 


- 


00CE0B08 


SDPnao 


- 


00CF0224 


SPno 


- 


00D00E0A 


PSDnoa 


- 


00D1066A 


PSDPxoxn 


- 


00D20705 


PDSnax 


- 


00D307A4 


SPDSoaxn 


- 


00D41D78 


SSPxPDxax 


- 


00D50CE9 


DPSanan 


- 


00D616EA 


PSDPSaoxx 


- 


00D70349 


DPSxan 


- 


00D80745 


PDSPxax 


- 


00D906E8 


SDPSaoxn 


- 


00DA1CE9 


DPSDanax 


- 


00DB0D75 


SPxDSxan 


- 


00DC0B04 


SPDnao 


- 


00DD0228 


SDno 


- 


00DE0268 


SDPxo 


- 


00DF08C8 


SDPano 


- 


00E003A5 


PDSoa 


- 


00E10185 


PDSoxn 


- 
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Table 1 1 .3: Raster-operation codes (continued) 



E2 


00E20746 


DSPDxax 


_ 


E3 


00E306EA 


PSDPaoxn 


- 


E4 


00E40748 


SDPSxax 


- 


E5 


00E506E5 


PDSPaoxn 


- 


E6 


00E61CE8 


SDPSanax 


- 


E7 


00E70D79 


SPxPDxan 


- 


E8 


00E81D74 


SSPxDSxax 


- 


E9 


00E95CE6 


DSPDSanaxxn 


- 


EA 


00EA02E9 


DPSao 


- 


EB 


00EB0849 


DPSxno 


- 


EC 


00EC02E8 


SDPao 


- 


ED 


00ED0848 


SDPxno 


- 


EE 


00EE0086 


DSo 


SRCPAINT 


EF 


00EF0A08 


SDPnoo 


- 


FO 


00F00021 


P 


PATCOPY 


Fl 


00F10885 


PDSono 


- 


F2 


00F20B05 


PDSnao 


- 


F3 


00F3022A 


PSno 


- 


F4 


00F40B0A 


PSDnao 


- 


F5 


00F50225 


PDno 


- 


F6 


00F60265 


PDSxo 


- 


F7 


00F708C5 


PDSano 


- 


F8 


00F802E5 


PDSao 


- 


F9 


00F90845 


PDSxno 


- 


FA 


00FA0089 


DPo 


- 


FB 


00FB0A09 


DPSnoo 


PATPAINT 


FC 


00FC008A 


PSo 


- 


FD 


00FD0A0A 


PSDnoo 


- 


FE 


00FE02A9 


DPSoo 


- 


FF 


00FF0062 


1 


WHITENESS 



For more information on topics related to raster-operation codes, see the 
following: 



Topic 



Reference 



Using raster-operation 
codes with GDI functions 

Setting the current drawing 
mode with SetROP2 



Reference, Volume 1: Chapter 2, 
"Graphics device interface functions," and 
Chapter 4, "Functions directory" 
Reference, Volume 1: Chapter 4, 
"Functions directory" 
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c 



A 



12 



Printer escapes 



This chapter contains an alphabetical list of the individual Microsoft 
Windows printer escapes. The printer escapes allow applications to access 
facilities of a particular output device that are not available directly 
through the graphics device interface (GDI). The escape calls are made by 
an application, translated by Windows, and then sent to the printer device 
driver. 



ABORTDOC 



Syntax short Escape(hDC, ABORTDOC, NULL, NULL, NULL) 

This escape terminates the current job, erasing everything the application 
has written to the device since the last ENDDOC escape. 

The ABORTDOC escape should be used to terminate: 

d Printing operations that do not specify an abort function using the 

SETABORTPROC escape 
□ Printing operations that have not yet reached their first NEWFRAME or 

NEXTBAND escape call 

Parameters hDC HDC Identifies the device context. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 
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ABORTDOC 



Comments If an application encounters a printing error or a canceled print operation, 
it must not attempt to terminate the operation by using the Escape 
function with either the ENDDOC or ABORTDOC escape. GDI 
automatically terminates the operation before returning the error value. 

If the application displays a dialog box to allow the user to cancel the 
print operation, it must send the ABORTDOC escape before destroying the 
dialog box. 

The application must send the ABORTDOC escape before freeing the 
procedure-instance address of the abort function, if any. 



BANDINFO 



Syntax short Escape(hDC, BANDINFO, sizeof(BANDINFOSTRUCT), lpInData, 
lpOutData) 

This escape copies information about a device with banding capabilities to 
a structure pointed to by the lpOutData parameter. It is implemented only 
for devices that use banding. 

Banding is a property of an output device that allows a page of output to 
be stored in a metafile and divided into bands, each of which is sent to the 
device to create a complete page. 

The information copied to the structure pointed to by lpOutData includes: 

■ A value that indicates whether there are graphics in the next band 
b A value that indicates whether there is text on the page 

■ A RECT data structure that contains a bounding rectangle for all 
graphics on the page 

The lpOutData parameter is NULL if no data are returned. 

The lpInData parameter specifies information sent by the application to 
the device driver. This information is read by the device driver only on the 
first BANDINFO escape call on a page. 



Parameters hDC 



lpInData 



lpOutData 



HDC Identifies the device context. 

BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT 

data structure that contains information to be passed to the 
driver. See the following "Comments" section for more 
information on the BANDINFOSTRUCT data structure. 

BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT 

data structure that contains information returned by the 
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BANDINFO 



driver. See the following "Comments" section for more 
information on the BANDINFOSTRUCT data structure. 

Return value The return value specifies the outcome of the escape. It is 1 if the escape is 
successful. It is zero if the function fails or is not implemented by the 
driver. 

Comments The BANDINFOSTRUCT data structure contains information about the 

contents of a page and supplies a bounding rectangle for graphics on the 
page. The following shows the format of BANDINFOSTRUCT: 

typedef struct { 

BOOL fGraphicsFlag; 

BOOL fTextFlag; 

RECT GraphicsRect; 
} BANDINFOSTRUCT; 

The BANDINFOSTRUCT structure has the following fields: 



Table 12.1 

Meaning of 

BANDINFOSTRUCT 

fields 



Field 



Description 



fGraphicsFlag Is TRUE if graphics are or are expected to be on the page or in 

the band; otherwise, it is FALSE. 
fTextFlag Is TRUE if text is or is expected to be on the page or in the band; 

otherwise, it is FALSE. 
GraphicsRect Contains a RECT data structure that supplies a bounding region 

for all graphics on the page. 

Table 12.1 shows the meaning of these fields, depending on which 
parameter contains the structure. 



Field 



When used in IplnData 



When used in IpOutData 



fGraphicsFlag 



fTextFlag 



GraphicsRect 



TRUE if the application is 
informing the driver that 
graphics are on the page. 
TRUE if the application is 
informing the driver that 
text is on the page. 
Supplies the bounding 
rectangle for all graphics 
on the page. 



TRUE if the driver is informing 
the application that it expects 
graphics in this band. 
TRUE if the driver is informing 
the application that it expects 
text in this band. 
No valid return data. 



An application should call this escape immediately after each call to the 
NEXTBAND escape. It is in reference to the band the driver returned to 
that escape. 

An application should use this escape in the following manner: 
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BEGIN PATH 



On the first band, the driver may give the application a full-page band 
and ask for text only (fGraphicsFlag is set to FALSE and fTextFlag is set to 
TRUE). The application sends only text to the driver. 

If in the first band the application indicated that it had graphics 
(fGraphicsFlag is set to TRUE), or that the driver encountered vector 
fonts, then the driver will band the rest of the page. If there are no 
graphics or vector fonts, then the next NEXTBAND will return an empty 
rectangle to indicate that the application should move on to the next page. 

If there are graphics but no vector fonts (the application set fGraphicsFlag 
to TRUE, but there were no graphics in the first full-page text band), then 
for subsequent bands the driver may optionally band only into the 
rectangle the application passed. This rectangle bounds all graphics on the 
page. If there are vector fonts, then the driver will band the entire width 
and depth of the page with fTextFlag set to TRUE. It will also set 
fGraphicsFlag to true if the application set it. 

The driver assumes that an application using BANDINFO will only send 
text in the first full-page text band since that is all the driver requested. 
Therefore, if the driver encounters a vector font or graphics in the band, it 
assumes they were generated by a text primitive and sets fTextFlag to 
TRUE for all subsequent graphics bands so they can be output as 
graphics. If the application does not satisfy this expectation, the image 
will still be generated properly, but the driver will spend time sending 
spurious text primitives to graphics bands. 

Older drivers written before the BANDINFO escape was designed used 
full-page banding for text. If a particular driver does not support the 
BANDINFO escape but sets RC_BANDING, the application can detect 
full-page banding for text by determining if the first band on the page 
covers the entire page. 



Syntax short Escape(hDC, BEGINJPATH, NULL, NULL, NULL) 

This escape opens a path. A path is a connected sequence of primitives 
drawn in succession to form a single polyline or polygon. Paths enable 
applications to draw complex borders, filled shapes, and clipping areas by 
supplying a collection of other primitives that define the desired shape. 

Printer escapes supporting paths enable applications to render images on 
sophisticated devices such as PostScript printers without generating huge 
polygons to simulate the images. 
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Return value 



Comments 



To draw a path, an application first issues the BEGIN_PATH escape. It 
then draws the primitives defining the border of the desired shape and 
issues an END_PATH escape. The END_PATH escape includes a parameter 
specifying how the path is to be rendered. 



Parameters hDC 



HDC Identifies the device context. 



The return value specifies the current path nesting level. If the escape is 
successful, the return value is the number of BEGIN_PATH escape calls 
without a corresponding END_PATH escape call. Otherwise, the return 
value is zero. 

An application may begin a subpath within another path. If the subpath is 
closed, it is treated exactly like a polygon. If it is open, it is treated exactly 
like a polyline. 

An application may use the CLIP_TO_PATH escape to define a clipping 
area corresponding to the interior or exterior of the currently open path. 



CLIP TO PATH 



Syntax short Escape(hDC, CLIP_TO_PATH, sizeof(int), lpClipMode, NULL) 

This escape defines a clipping area bounded by the currently open path. It 
enables the application to save and restore the current clipping area and 
to set up an inclusive or exclusive clipping area bounded by the currently 
open path. If the path defines an inclusive clipping area, portions of 
primitives falling outside the interior bounded by the path are clipped. If 
the path defines an exclusive clipping area, portions of primitives falling 
inside the interior are clipped. 

Parameters hDC HDC Identifies the device context. 

lpClipMode LPINT Points to a short integer specifying the clipping mode. 
It can be one of the following values: 

d CLIP_SAVE (0) Saves the current clipping area. 
a CLIP_RESTORE (1) Restores the previous clipping area, 
p CLIPJNCLUSIVE (2) Sets an inclusive clipping area. 
d CLIP_EXCLUSIVE (3) Sets an exclusive clipping area. 

The return value specifies the outcome of the escape. It is nonzero if the 
escape was successful. Otherwise, it is zero. 

To clip a set of primitives against a path, an application should follow 
these steps: 

1. Save the current clipping area using the CLIP_TO_PATH escape. 



Return value 



Comments 
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2. Begin a path using the BEGIN_PATH escape. 

3. Draw the primitives bounding the clipping area. 

4. Close the path using the END_PATH escape. 

5. Set the clipping area using the CLIP_TO_PATH escape. 

6. Draw the primitives to be clipped. 

7. Restore the original clipping area using the CLIP_TO_PATH escape. 



DEVICEDATA 



Syntax short Escape(hDC, DEVICEDATA, nCount, lpInData, lpOutData) 

This escape is identical to the PASSTH ROUGH escape. See the description 
of PASSTHROUGH for further information. 



DRAFTMODE 



Syntax short Escape(hDC, DRAFTMODE, sizeof(int), lpDraftMode, NULL) 

This escape turns draft mode off or on. Turning draft mode on instructs 
the device driver to print faster and with lower quality (if necessary). The 
draft mode can be changed only at page boundaries, for example, after a 
NEWFRAME escape directing the driver to advance to a new page. 



Parameters hDC 



HDC Identifies the device context. 



Return value 



lpDraftMode LPINT Points to a short-integer value that specifies the draft 
mode. It may be one of the following values: 

■ Specifies draft mode off. 

■ 1 Specifies draft mode on. 

The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 



Comments The default draft mode is off. 



DRAWPATTERNRECT 



Syntax short Escape(hDC, DRAWPATTERNRECT, sizeof(PRECTSTRUCT), 
lpInData, NULL) 

This escape creates a pattern, gray scale, or solid black rectangle by using 
the pattern/rule capabilities of Page Control Language (PCL) on 
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Return value 



Comments 



DRAWPATTERNRECT 



Hewlett-Packard® LaserJet® or LaserJet-compatible printers. A gray scale 
is a gray pattern that contains a specific mixture of black and white pixels. 



Parameters hDC 



IpInData 



HDC Identifies the device context. 

PRECT_STRUCT FAR * Points to a PRECT_STRUCT data 
structure that describes the rectangle. See the following 
"Comments" section for more information on the 
PRECT STRUCT data structure. 



The return value specifies the outcome of the escape. It is 1 if the escape is 
successful. Otherwise, it is zero. 

The IpInData parameter points to a PRECT_STRUCT data structure that 
defines the rectangle to be created. The PRECT_STRUCT structure has the 
following format: 

typedef struct { 

POINT prPosition; 

POINT prSize; 

WORD prStyle; 

WORD prPattern; 
} PRECT_STRUCT; 

This structure has the following fields: 



Field 



Description 



prPosition Specifies the upper-left corner of the rectangle. 

prSize Specifies the lower-right corner of the rectangle. 

prStyle Specifies the type of pattern. It may be one of the following values: 

Value Meaning 

Black rule 

1 White rule that erases bitmap data previously written to 
same area; this pattern is available on the HP LaserJet IIP 
only. 

2 Gray scale 

3 HP-defined 

prPattern Specifies the pattern. It is ignored for a black rule. It specifies the 

percentage of gray for a gray-scale pattern. It represents one of six 
Hewlett-Packard-defined patterns. 

An application should use the QUERYESCSUPPORT escape to determine 
whether a device is capable of drawing patterns and rules before using the 
DRAWPATTERNRECT escape. If an application uses the BANDINFO 
escape, all patterns and rectangles sent by using DRAWPATTERNRECT 
should be treated as text and sent on a text band. 
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Do not try to erase patterns and rules created with the 
DRAWPATTERNRECT escape by placing opaque objects over them. To 
erase such patterns and rules, use the function calls provided by GDI. 



ENABLEDUPLEX 



Syntax short Escape(hDC, ENABLEDUPLEX, sizeof (WORD), lpInData, NULL) 

This escape enables the duplex printing capabilities of a printer. A device 
that possesses duplex printing capabilities is able to print on both sides of 
the output medium. 

Parameters hDC 



Return value 



Comments 



lpInData 



HDC Identifies the device context. 

WORD FAR * Points to an unsigned 16-bit integer that 
specifies whether duplex or simplex printing is used. It may 
be one of the following values: 

b Simplex 

■ 1 Duplex with vertical binding 

■ 2 Duplex with horizontal binding 

The return value specifies the outcome of the escape. It is 1 if the escape is 
successful. Otherwise, it is zero. 

An application should use the QUERYESCSUPPORT escape to determine 
whether an output device is capable of creating duplex output. If 
QUERYESCSUPPORT returns a nonzero value, the application should 
send the ENABLEDUPLEX escape even if simplex printing is desired. This 
guarantees replacement of any values set in the driver-specific dialog box. 
If duplex printing is enabled and an uneven number of NEXTFRAME 
escapes are sent to the driver prior to the ENDDOC escape, the driver will 
eject an additional page before ending the print job. 



ENABLEPAIRKERNING 



Syntax short Escape(hDC, ENABLEPAIRKERNING, sizeof(int), lpNewKernFlag, 
lpOldKernFlag) 

This escape enables or disables the driver's ability to kern character pairs 
automatically. Kerning is the process of adding or subtracting space 
between characters in a string of text. 

When pair kerning is enabled, the driver automatically kerns those pairs 
of characters that are listed in the font's character-pair kerning table. The 
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driver reflects this kerning both on the printer and in GetTextExtent 
function calls. 



Parameters hDC 



HDC Identifies the device context. 



IpNewKernFlag LPINT Points to a short-integer value that specifies 

whether automatic pair kerning is to be enabled (1) or 
disabled (0). 

IpOldKernFlag LPINT Points to a short-integer value that will receive the 
previous automatic pair-kerning value. 

Return value The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful or not implemented. 

Comments The default state of this escape is zero; automatic character-pair kerning is 
disabled. 

A driver does not have to support the ENABLEPAIRKERNING escape just 
because it supplies the character-pair kerning table to the application via 
the GETPAIRKERNTABLE escape. In the case where the 
GETPAIRKERNTABLE escape is supported but the 

ENABLEPAIRKERNING escape is not, the application must properly space 
the kerned characters on the output device using the ExtTextOut function. 



ENABLERELATIVEWIDTHS 



Syntax short Escape(hDC, ENABLERELATIVEWIDTHS, sizeof(int), 
lpNewWidthFlag, lpOldWidthFlag) 

This escape enables or disables relative character widths. When relative 
widths are disabled (the default), each character's width can be expressed 
as a number of device units. This guarantees that the extent of a string will 
equal the sum of the extents of the characters in the string. This allows 
applications to build an extent table by using one-character GetTextExtent 
function calls. 

When relative widths are enabled, the sum of a string may not equal the 
sum of the widths of the characters. Applications that enable this feature 
are expected to retrieve the font's extent table and compute relatively 
scaled string widths. 



Parameters hDC 



lpNewWidthFlag 



HDC Identifies the device context. 

LPINT Points to a short-integer value that specifies 
whether relative widths are to be enabled (1) or 
disabled (0). 
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Return value 



Comments 



IpOldWidthFlag LPINT Points to a short-integer value that will receive 
the previous relative character width value. 

The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful or not implemented. 

The default state of this escape is zero; relative character widths are 
disabled. 

The values specified as font units and accepted and returned by the 
escapes described in this chapter are returned in the relative units of the 
font when the ENABLERELATIVEWIDTHS escape is enabled. 

It is assumed that only linear-scaling devices will be dealt with in a 
relative mode. Nonlinear-scaling devices do not implement this escape. 



ENDDOC 



Syntax short Escape(hDC, ENDDOC, NULL, NULL, NULL) 

This escape ends a print job started by a STARTDOC escape. 

Parameters hDC HDC Identifies the device context. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 

Comments If an application encounters a printing error or a canceled print operation, 
it must not attempt to terminate the operation by using the Escape 
function with either the ENDDOC or ABORTDOC escape. GDI 
automatically terminates the operation before returning the error value. 

If the application displays a dialog box to allow the user to cancel the 
print operation, it must send the ENDDOC escape before destroying the 
dialog box. 

The application must send the ENDDOC escape before freeing the 
procedure-instance address of the abort function, if any. 

END.PATH 

Syntax short Escape(hDC, END_PATH, sizeof (PATHJNFO), lpInData, NULL) 

This escape ends a path. A path is a connected sequence of primitives 
drawn in succession to form a single polyline or polygon. Paths enable 
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Return value 



Comments 



applications to draw complex borders, filled shapes, and clipping areas by 
supplying a collection of other primitives defining the desired shape. 

Printer escapes supporting paths enable applications to render images on 
sophisticated devices such as PostScript printers without generating huge 
polygons to simulate them. 

To draw a path, an application first issues the BEGIN_PATH escape. It 
then draws the primitives defining the border of the desired shape and 
issues an END_PATH escape. 

The END_PATH escape takes as a parameter a pointer to a structure 
specifying the manner in which the path is to be rendered. The structure 
specifies whether or not the path is to be drawn and whether it is open or 
closed. Open paths define polylines, and closed paths define tillable 
polygons. 



Parameters hDC 



IpInData 



HDC Identifies the device context. 

PATHJNFO FAR * Points to a PATHJNFO data structure 
that defines how the path is to be rendered. See the 
following "Comments" section for more information on this 
data structure. 



The return value specifies the current path nesting level. If the escape is 
successful, the return value is the number of BEGIN_PATH escape calls 
without a corresponding END_PATH call. Otherwise, the return value is 
-1. 

An application may begin a subpath within another path. If the subpath is 
closed, it is treated exactly like a polygon. If it is open, it is treated exactly 
like a polyline. 

An application may use the CLIP_TO_PATH escape to define a clipping 
area corresponding to the interior or exterior of the currently open path. 

The IpInData parameter points to a PATHJNFO data structure that 
specifies how to render the path. This data structure has the following 
form: 

typedef struct { 

short RenderMode; 

BYTE FillMode; 

BYTE BkMode; 

LOGPEN Pen; 

LOGBRUSH Brush; 

DWORD BkColor; 
} PATHJNFO; 



Chapter 12, Printer escapes 



163 



END PATH 



The PATHJNFO structure has the following fields: 



Field Description 



RenderMode 



FillMode 



BkMode 



Specifies how the path is to be rendered. It may be one of the 
following values: 



Value 

NO_DISPLAY (0) 
OPEN (1) 
CLOSED (2) 



Meaning 

The path is not drawn. 

The path is drawn as an open polygon. 

The path is drawn as a closed polygon. 



Specifies how the path is to be filled. It can be one of the following 
values: 



Value 

ALTERNATE (1) 

WINDING (2) 



Meaning 

The fill is done using the alternate fill 

algorithm. 

The fill is done using the winding fill 

algorithm. 



Specifies the background mode for filling the path. It can be one 
of the following values: 

Value Meaning 

OPAQUE The background is filled with the 

background color before the brush is drawn. 
TRANSPARENT The background is not changed. 

Pen Specifies the pen with which the path is to be drawn. If 

RenderMode is set to NO_DISPLAY, the pen is ignored. 
Brush Specifies the brush with which the path is to be filled. If 

RenderMode is set to NO_DISPLAY or OPEN, the brush is 

ignored. 
BkColor Specifies the color with which the path is filled if BkMode is set to 

OPAQUE. 



ENUMPAPERBINS 



Syntax short Escape(hDC, ENUMPAPERBINS, sizeof(int), lpNumBins, 
lpOutData) 

This escape retrieves attribute information about a specified number of 
paper bins. The GETSETPAPERBINS escape retrieves the number of bins 
available on a printer. This escape is provided only for backward 
compatibility. An application should call the ExtDeviceMode function 
instead. 



Parameters hDC 



lpNumBins 



HDC Identifies the device context. 

LPINT Points to an integer that specifies the number of bins 
for which information is to be retrieved. 
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Comments 



ENUMPAPERBINS 



IpOutData LPSTR Points to a data structure to which information about 
the paper bins is copied. The size of the structure depends 
on the number of bins for which information was requested. 
See the following "Comments" section for a description of 
this data structure. 

The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful or not implemented. 

The data structure to which the IpOutData parameter points consists of 
two arrays. The first is an array of short integers containing the paper-bin 
identifier numbers in the following format: 



short 



BinList [cBinMax] 



The number of integers in the array (cBinMax) is equal to the value 
pointed to by the IpNumBins parameter. 

The second array in the data structure to which IpOutData points is an 
array of characters in the following format: 

char PaperNames [cBinMax] [cchBinName] 

The cBinMax value is equal to the value pointed to by the IpNumBins 
parameter; the cchBinName value is the length of each string (currently 24). 



ENUMPAPERMETRICS 



Syntax short Escape(hDC, ENUMPAPERMETRICS, sizeof(int), lpMode, 
IpOutData) 

This escape performs one of two functions according to the mode: 

□ It determines the number of paper types supported and returns this 
value, which can then be used to allocate an array of RECT data 
structures. 

□ It returns one or more RECT data structures that define the areas on the 
page that can receive an image. 

This escape is provided only for backward compatibility. An application 
should call the ExtDeviceMode function instead. 

Parameters hDC HDC Identifies the device context. 

lpMode LPINT Points to an integer that specifies the mode for the 

escape. It can be one of the following values: 
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IpOutData 



■ The return value indicates how many RECT data 
structures are required to contain the information about 
the available paper types. 

■ 1 The array of RECT structures to which IpOutData points 
is filled with the information. 

LPRECT Points to an array of RECT data structures that 
return all the areas that can receive an image. 



Return value The return value is positive if successful, zero if the escape is not 
implemented, and negative if an error occurred. 



EPSPRINTING 

Syntax short Escape(hDC, EPSPRINTING, sizeof (BOOL), lpBool, NULL) 

This escape suppresses the output of the Windows PostScript header 
control section, which is about 7K. If an application uses this escape, no 
GDI calls are allowed. 

Parameters hDC HDC Identifies the device context. 

lpBool BOOL FAR * Points to a Boolean value indicating that 

downloading should be enabled (TRUE) or disabled 
(FALSE). 

Return value The return value is positive if successful, zero if the escape is not 
implemented, and negative if an error occurred. 

EXT_DEVICE_CAPS 

Syntax short Escape(hDC, EXT_DEVICE_CAPS, sizeof(int), lplndex, lpCaps) 

This escape retrieves information about device-specific capabilities. It 
supplements the GetDeviceCaps function. 

Parameters hDC HDC Identifies the device context. 

lplndex LPINT Points to a short integer specifying the index of the 

capability to be retrieved. It can be any one of the following 
values: 

n R2_CAPS (1) The lpCaps parameter indicates which of the 
16 binary raster operations the device driver supports. A 
bit will be set for each supported raster operation. For 
further information, see the description of the SetROP2 
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function in Chapter 4, "Functions directory," in Reference, 
Volume 1. 

a PATTERN_CAPS (2) The IpCaps parameter returns the 
maximum dimensions of a pattern brush bitmap. The 
low-order word of the capability value contains the 
maximum width of a pattern brush bitmap, and the high- 
order word contains the maximum height. 

□ PATH_CAPS (3) The IpCaps parameter indicates whether 
the device is capable of creating paths using alternate and 
winding interiors, and whether the device can do exclusive 
or inclusive clipping to path interiors. The path capabilities 
are obtained using the logical OR operation on the 
following values: 

• PATH_ALTERNATE (1) 

• PATH_WINDING (2) 

o PATHJNCLUSIVE (4) 

• PATH_EXCLUSIVE (8) 

□ POLYGON_CAPS (4) The IpCaps parameter returns the 
maximum number of polygon points supported by the 
device. The capability value is an unsigned value 
specifying the maximum number of points. 

□ PATTERN_COLOR_CAPS (5) The IpCaps parameter 
indicates whether the device can convert monochrome 
pattern bitmaps to color. The capability value is 1 if the 
device can do pattern bitmap color conversions, and zero 
if it cannot. 

d R2_TEXT_CAPS (6) The IpCaps parameter indicates 
whether the device is capable of performing binary raster 
operations on text. The low-order word of the capability 
value specifies which raster operations are supported for 
text. A bit is set for each supported raster operation, as in 
the R2_CAPS escape. The high-order word specifies the 
type of text to which the raster capabilities apply. It is 
obtained by applying the logical OR operation to the 
following values together: 

• RASTERTEXT (1) 

• DEVICE_TEXT (2) 

• VECTORJTEXT (4) 

□ POLYMODE_CAPS (7) Specifies which poly modes are 
supported by the printer driver. The capability value is 
obtained by using the bitwise OR operator to combine a bit 
in the corresponding position for each supported poly 
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IpCaps 



mode. For example, if the printer supports the 
PM_POLYSCANLINE and PM_BEZIER poly modes, the 
capability value would be: 

(1 PM_POLYSCANLINE) (PM_BEZIER) 

See the description of the SET_POLY_MODE escape for 
information on the poly modes. 

DWORD FAR * Points to a 32-bit integer to which the 
capabilities will be copied. 

Return value The return value is nonzero if the specified extended capability is 
supported, and zero if it is not. 

EXTTEXTOUT 

Syntax short Escape(hDC, EXTTEXTOUT, sizeof(EXTTEXT_STRUCT), lpInData, 
NULL) 

This escape provides an efficient way for the application to call the GDI 
TextOut function when justification, letter spacing, and/or kerning are 
involved. 

This function is provided only for backward compatibility. New 
applications should use the GDI ExtTextOut function instead. 

Parameters hDC HDC Identifies the device context. 

lpInData EXTTEXT_STRUCT FAR * Points to an EXTTEXT_STRUCT 

data structure that specifies the initial position, characters, 
and character widths of the string. See the following 
"Comments" section for more information on the 
EXTTEXT_STRUCT data structure. 

The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful or not implemented. 



Return value 



Comments The EXTEXT_STRUCT data structure has the following format: 



typedef struct { 

WORD X; 

WORD Y; 

WORD FAR *lpText; 

WORD FAR *lpWidths; 
} EXTTEXT_STRUCT; 



This structure has the following fields. 
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Field 



Description 



X Specifies the x-coordinate of the upper-left corner of the string's 

starting point. 

Y Specifies the y-coordinate of the upper-left corner of the string's 

starting point. 

IpText Points to an array of cch character codes, where cch is the number of 

bytes in the string (cch is also the number of words in the width 
array). 

IpWidths Points to an array of cch character widths to use when printing the 

string. The first character appears at (X,Y), the second at (X + 
lpWidths[0],Y), the third at (X + lpWidths[0] + lpWidths[l],Y), and 
so on. These character widths are specified in the font units of the 
currently selected font. (The character widths will always be equal 
to device units unless the application has enabled relative character 
widths.) 

The units contained in the width array are specified as font units of 
the device. 



FLUSHOUTPUT 



Syntax short Escape(hDC, FLUSHOUTPUT, NULL, NULL, NULL) 

This escape clears all output from the device's buffer. 

Parameters hDC HDC Identifies the device context. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 



GETCOLORTABLE 



Syntax short Escape(hDC, GETCOLORTABLE, sizeof(int), lplndex, lpColor) 

This escape retrieves an RGB color-table entry and copies it to the location 
specified by the lpColor parameter. 

Parameters hDC HDC Identifies the device context. 

lplndex LPINT Points to a short-integer value that specifies the index 

of a color-table entry. Color-table indexes start at zero for the 
first table entry. 

lpColor DWORD FAR * Points to the long-integer value that will 

receive the RGB color value for the given entry. 
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Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 



GETEXTENDEDTEXTMETRICS 



Syntax short Escape(hDC, GETEXTENDEDTEXTMETRICS, sizeof(WORD), 
lpInData, lpOutData) 

This escape fills the buffer pointed to by the lpOutData parameter with the 
extended text metrics for the selected font. 

Parameters hDC HDC Identifies the device context. 

lpInData WORD FAR * Points to an unsigned 16-bit integer that 

specifies the number of bytes pointed to by the lpOutData 
parameter. 

lpOutData EXTTEXTMETRIC FAR * Points to an EXTTEXTMETRIC data 
structure. See the following "Comments" section for a 
description of this data structure. 

Return value The return value specifies the number of bytes copied to the buffer 

pointed to by the lpOutData parameter. This value will never exceed that 
specified in the nSize field pointed to by the lpInData parameter. The 
return value is zero if the escape fails or is not implemented. 

Comments The lpOutData parameter points to an EXTTEXTMETRIC data structure 
which has the following format: 

typedef struct 

short etmSize; 

short etmPointSize; 

short etmOrientation; 

short etmMasterHeight; 

short etmMinScale; 

short etmMaxScale; 

short etmMasterUnits; 

short etmCapHeight; 

short etmXHeight; 

short etmLowerCaseAscent; 

short etmLowerCaseDescent; 

short etmSlant; 

short etmSuperScript; 

short etmSubScript; 

short etmSuperScriptSize; 

short etmSubScriptSize; 

short etmUnderlineOffset; 
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short etmUnderlineWidth; 

short etmDoubleUpperUnderlineOf f set ; 

short etmDoubleLowerUnderlineOffset; 

short etmDoubleUpperUnderlineWidth; 

short etmDoubleLowerUnderlineWidth; 

short etmStrikeOutOffset; 

short etmStrikeOutWidth; 

WORD etmKernPairs; 

WORD etmKernTracks; 

}EXTTEXTMETRIC; 

The EXTTEXTMETRIC data structure has the following fields: 



Field 



Description 



etmSize 
etmPointSize 



etmOrientation 



etmMasterHeight 
etmMinScale 



etmMaxScale 



Specifies the size of the structure in bytes. 
Specifies the nominal point size of this font 
in twips (twentieths of a point, or 1/1440 
inch). This is the intended size of the font; 
the actual size may differ slightly depending 
on the resolution of the device. 
Specifies the orientation of the font. The 
etmOrientation field may be any of the 
following values: 



Value 


Meaning 





Either orientation 


1 


Portrait 


2 


Landscape 



These values refer to the ability of this font 
to be placed on a page with the given 
orientation. A portrait page has a height that 
is greater than its width. A landscape page 
has a width that is greater than its height. 
Specifies the font size in device units for 
which the values in this font's extent table 
are exact. 

Specifies the minimum valid size for this 
font. The following equation illustrates how 
the minimum point size is determined: 

smallest point size 

= etmMinScale * 72/dfVertRes 

The value 72 represents the number of points 
per inch. The dfVertRes value is the number 
of dots per inch. 

Specifies the maximum valid size for this 
font. The following equation illustrates how 
the maximum point size is determined: 

largest point size 

= etmMaxScale * 72/dfVertRes 
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etmMasterUnits 

etmCapHeight 

etmXHeight 

etmLowerCaseAscent 

etmLowerCaseDescent 

etmSlant 

etmSuperScript 

etmSubScript 

etmSuperScriptSize 

etmSubScriptSize 

etmUnderlineOffset 

etmUnderlineWidth 
etmDoubleUpperUnderlineOffset 

etmDoubleLowerUnderlineOffset 

etmDoubleUpperUnderlineWidth 



The value 72 represents the number of points 

per inch. The dfVertRes value is the number 

of dots per inch. 

Specifies the integer number of units per em 

where an em equals etmMasterHeight. That 

is, etmMasterUnits is emtMasterHeight 

expressed in font units rather than device 

units. 

Specifies the height in font units of 

uppercase characters in the font. Typically, 

this is the height of the capital H. 

Specifies the height in font units of lowercase 

characters in the font. Typically, this is the 

height of the lowercase x. 

Specifies the distance in font units that the 

ascender of lowercase letters extends above 

the baseline. Typically, this is the height of 

the lowercase d. 

Specifies the distance in font units that the 

descender of lowercase letters extends below 

the baseline. Typically, this is specified for 

the descender of the lowercase p. 

Specifies for an italicized or slanted font the 

angle of the slant measured in tenths of a 

degree clockwise from the upright version of 

the font. 

Specifies in font units the recommended 

amount to offset superscript characters from 

the baseline. This is typically a negative 

value. 

Specifies in font units the recommended 

amount to offset subscript characters from 

the baseline. This is typically a positive 

value. 

Specifies in font units the recommended size 

of superscript characters for this font. 

Specifies in font units the recommended size 

of subscript characters for this font. 

Specifies in font units the offset downward 

from the baseline where the top of a single 

underline bar should appear. 

Specifies in font units the thickness of the 

underline bar. 

Specifies the offset in font units downward 

from the baseline where the top of the upper 

double underline bar should appear. 

Specifies the offset in font units downward 

from the baseline where the top of the lower 

double underline bar should appear. 

Specifies in font units the thickness of the 

upper underline bar. 
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etmStrikeOutOffset 



etmStrikeOutWidth 



etmKernPairs 



etmKernTracks 



GETEXTENDEDTEXTMETRICS 



Specifies in font units the thickness of the 
lower underline bar. 
Specifies in font units the offset upward 
from the baseline where the top of a strike- 
out bar should appear. 
Specifies the thickness in font units of the 
strike-out bar. 

Specifies the number of character kerning 
pairs defined for this font. An application 
can use this value to calculate the size of the 
pair-kern table returned by the 
GETPAIRKERNTABLE escape. It will not be 
greater than 512 kern pairs. 
Specifies the number of kerning tracks 
defined for this font. An application can use 
this value to calculate the size of the track- 
kern table returned by the 
GETTRACKKERNTABLE escape. It will not 
be greater than 16 kern tracks. 



The values returned in many of the fields of the EXTTEXTMETRIC 
structure are affected by whether relative character widths are enabled or 
disabled. For more information, see the description of 
ENABLERELATIVEWIDTHS escape earlier in this chapter. 



GETEXTENTTABLE 



Syntax short Escape(hDC, GETEXTENTTABLE, 

sizeof(CHAR_RANGE_STRUCT), lpInData, lpOutData) 

This escape retrieves the width (extent) of individual characters from a 
group of consecutive characters in the selected font's character set. 



Parameters hDC 



Return value 



lpInData 



lpOutData 



HDC Identifies the device context. 

LPSTR Points to a CHAR_RANGE_STRUCT data structure 
that defines the range of characters for which the width is to 
be retrieved. See the following "Comments" section for 
more information on the CHAR_RANGE_STRUCT data 
structure. 

LPINT Points to an array of short integers that receives the 
character widths. The size of the array must be at least 
(chLast - chFirst + 1). 



The return value specifies the outcome of the escape. It is 1 if the escape is 
successful, and zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 
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Comments The IpInData parameter points to a CHAR_RANGE_STRUCT data 

structure that defines the range of characters for which the width is to be 
retrieved. The CHAR_RANGE_STRUCT structure has the following 
format: 

typedef struct { 

BYTE chFirst; 

BYTE chLast; 
} CHAR_RMGE_STRUCT 

This structure has the following fields: 



Field 



Description 



chFirst Specifies the character code of the first character whose width is to be 

retrieved. 
chLast Specifies the character code of the last character whose width is to be 

retrieved. 

The values retrieved are affected by whether relative character widths are 
enabled or disabled. For more information, see the 
ENABLERELATIVEWIDTHS escape, earlier in this chapter. 



GETFACENAME 



Syntax short Escape(hDC, GETFACENAME, NULL, NULL, lpFaceName) 

This escape retrieves the face name of the current physical font. 

Parameters hDC HDC Identifies the device context. 

lpFaceName LPSTR Points to a buffer of characters to receive the face 
name. This buffer must be at least 60 bytes in length. 

Return value The return value is positive if the escape was successful, zero if the escape 
is not implemented, or negative if an error occurred. 



GETPAIRKERNTABLE 



Syntax short Escape(hDC, GETPAIRKERNTABLE, NULL, NULL, lpOutData) 

This escape fills the buffer pointed to by the lpOutData parameter with the 
character-pair kerning table for the selected font. 

Parameters hDC HDC Identifies the device context. 
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IpOutData KERNPAIR FAR * Points to an array of KERNPAIR data 

structures. This array must be large enough to accommodate 
the font's entire character-pair kerning table. The number of 
character-kerning pairs in the font can be obtained from the 
EXTTEXTMETRIC data structure returned by the 
GETEXTENDEDTEXTMETRICS escape. See the following 
"Comments" section for the format of the KERNPAIR data 
structure. 

Return value The return value specifies the number of KERNPAIR structures copied to 
the buffer. This value is zero if the font does not have kerning pairs 
defined, the escape fails, or is not implemented. 

Comments The KERNPAIR data structure has the following format: 

typedef struc ( 
union { 

BYTE each [2]; /* UNION: 'each' and 'both' 

share the same memory */ 
WORD both; 
} kpPair; 
short kpKernAmount; 
} KERNPAIR; 

The KERNPAIR structure contains the following fields: 



Field 



Description 



kpPair.each[0] Specifies the character code for the first character in the 

kerning pair. 
kpPair.each[1] Specifies the character code for the second character in the 

kerning pair. 
kpPair.both Specifies a WORD in which the first character in the kerning 

pair is in the low-order byte and the second character is in the 

high-order byte. 
kpKernAmount Specifies the signed amount that this pair will be kerned if they 

appear side by side in the same font and size. This value is 

typically negative since pair-kerning usually results in two 

characters being set more tightly than normal. 

The array of KERNPAIR structures is sorted in increasing order by the 
kpPair.both field. 

The values returned in the KERNPAIR structures are affected by whether 
relative character widths are enabled or disabled. For more information, 
see the description of the ENABLERELATIVEWIDTHS escape earlier in this 
chapter. 
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GETPHYSPAGESIZE 



Syntax short Escape(hDC, GETPHYSPAGESIZE, NULL, NULL, lpDimensions) 

This escape retrieves the physical page size and copies it to the location 
pointed to by the lpDimensions parameter. 

Parameters hDC HDC Identifies the device context. 

lpDimensions LPPOINT Points to a POINT data structure that will receive 
the physical page dimensions. The x field of the POINT 
data structure receives the horizontal size in device units, 
and the y field receives the vertical size in device units. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 



GETPRINTINGOFFSET 



Syntax short Escape(hDC, GETPRINTINGOFFSET, NULL, NULL, lpOffset) 

This escape retrieves the offset from the upper-left corner of the physical 
page where the actual printing or drawing begins. This escape is generally 
not useful for devices that allow the user to set the origin of the printable 
area directly. 



Parameters hDC 



Return value 



HDC Identifies the device context. 



lpOffset 



LPPOINT Points to a POINT structure that will receive the 
printing offset. The x field of the POINT structure receives 
the horizontal coordinate of the printing offset in device 
units, and the y field receives the vertical coordinate of the 
printing offset in device units. 

The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 



GETSCALINGFACTOR 



Syntax short Escape(hDC, GETSCALINGFACTOR, NULL, NULL, lpFactors) 

This escape retrieves the scaling factors for the x- and y-axes of a printing 
device. For each scaling factor, the escape copies an exponent of 2 to the 
location pointed to by the lpFactors parameter. For example, the value 3 is 
copied to lpFactors if the scaling factor is 8. 
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Return value 



Scaling factors are used by printing devices that support graphics at a 
smaller resolution than text. 



Parameters hDC 



IpFactors 



HDC Identifies the device context. 

LPPOINT Points to the POINT data structure that will receive 
the scaling factor. The x field of the POINT structure receives 
the scaling factor for the x-axis, and the y field receives the 
scaling factor for the y-axis. 



The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 



GETSETPAPERBINS 



Syntax short Escape(hDC, GETSETPAPERBINS, nCount, lpInData, lpOutData) 

This escape retrieves the number of paper bins available on a printer and 
sets the current paper bin. See the following "Comments" section for more 
information on the actions performed by this escape. 



Parameters hDC 

nCount 



lpInData 



Comments 



lpOutData 



HDC Identifies the device context. 

int Specifies the number of bytes pointed to by the lpInData 
parameter. 

Binlnfo FAR * Points to a Binlnfo data structure that specifies 
the new paper bin. It may be set to NULL. 

Binlnfo FAR * Points to a Binlnfo data structure that contains 
information about the current or previous paper bin and the 
number of bins available. 



There are three possible actions for this escape, depending on the values 
passed in the lpInData and lpOutData parameters: 

lpInData lpOutData Action 

NULL Binlnfo Retrieves the number of bins and the number of the 

current bin. 
Binlnfo Binlnfo Sets the current bin to the number specified in the 

BinNumber field of the data structure to which lpInData 

points and retrieves the number of the previous bin. 
Binlnfo NULL Sets the current bin to the number specified in the 

BinNumber field of the data structure to which lpInData 

points. 

The Binlnfo data structure has the following format: 
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typedef struct! 

DWORD BinNumber; 

DWORD NbrofBins; 

DWORD Reserved; 

DWORD Reserved; 

DWORD Reserved; 

DWORD Reserved; 
} Binlnfo; 



The Binlnfo structure has the following fields: 



Field 



Description 



BinNumber Identifies the current or previous paper bin. 
NbrofBins Specifies the number of paper bins available. 

When setting a new bin, the setting does not take effect until a new device 
context is created (without initialization data). The setting will take 
immediate effect if the high bit of the bin number is set, so that the next 
page printed will come from the new bin. For example, 0x8001 uses the 
second bin immediately whenever 0x0001 sets the same bin as the default 
for later print jobs. 

In general, only the immediate-selection form should be used by 
applications. Setting the bin for future print jobs is supported for 
backward compatibility to an earlier form of this escape which appeared 
in some versions of HP's Page Control Language (PCL) and PostScript. 



GETSETPAPERMETRICS 



Synfax short Escape(hDC, GETSETPAPERMETRICS, sizeof(RECT), lpNewPaper, 
lpPrevPaper) 

This escape sets the paper type according to the given paper metrics 
information. It also retrieves the current printer's paper metrics 
information. This escape is provided only for backward compatibility. An 
application should call the ExtDeviceMode function instead. 

This escape expects a RECT data structure representing the imageable 
area of the physical page and assumes the origin is in the upper-left 
corner. 



Parameters hDC 



HDC Identifies the device context. 



lpNewPaper LPRECT Points to a RECT data structure that defines the 
new imageable area. 
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IpPrevPaper LPRECT Points to a RECT data structure that receives the 
previous imageable area. 

Return value The return value is positive if successful, zero if the escape is not 
implemented, and negative if an error occurs. 

Comments This escape is provided only for backward compatibility. New 

applications should use the GDI DeviceCapabilities and ExtDeviceMode 
functions instead. 



GETSETPAPERORIENT 



Syntax short Escape(hDC, GETSETPAPERORIENT, nCount, lpInData, NULL) 

This escape returns or sets the current paper orientation. This escape is 
provided only for backward compatibility. An application should call the 
ExtDeviceMode function instead. 



Parameters hDC 



Return value 



Comments 



HDC Identifies the device context. 

nCount Specifies the number of bytes pointed to by the lpInData 

parameter. 

lpInData ORIENT FAR * Points to an ORIENT data structure that 

specifies the new paper orientation. See the following 
"Comments" section for a description of this data structure. 
It may be set to NULL, in which case the 
GETSETPAPERORIENT escape returns the current paper 
orientation. 

The return value specifies the current orientation if lpInData is NULL; 
otherwise, it is the previous orientation. The return value is -1 if the 
escape failed. 

This escape is provided only for backward compatibility. New 
applications should use the GDI DeviceCapabilities and ExtDeviceMode 
functions instead. 

The ORIENT data structure has the following format: 



typedef struct! 


DWORD 


Orientation; 


DWORD 


Reserved; 


DWORD 


Reserved; 


DWORD 


Reserved; 


DWORD 


Reserved; 


} ORIENT; 
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The Orientation field can be either of these values: 



Value 



Meaning 



The new orientation is portrait. 
The new orientation is landscape. 



This escape is also known as GETSETPAPERORIENTATION. 



GETSETSCREENPARAMS 



Syntax 



short Escape(hDC, GETSETSCREENPARAMS, sizeof(SCREENP ARAMS), 
lpInData, lpOutData) 

This escape retrieves or sets the current screen information for rendering 
halftones. 



Parameters 



hDC HDC Identifies the device context. 

lpInData SCREENPARAMS FAR * Points to a SCREENPARAMS data 

structure that contains the new screen information. This 
parameter may be NULL. 

lpOutData SCREENPARAMS FAR * Points to a SCREENPARAMS data 
structure that retrieves the previous screen information. This 
parameter may be NULL. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 

Comments This escape affects how device-independent bitmaps (DIBs) are rendered 
and how color objects are filled. 

The SCREENPARAMS data structure has the following format: 

typedef struct { 

int angle; 

int frequency; 

DWORD types; 
} SCREENPARAMS; 

The SCREENPARAMS structure has the following fields: 



Field 



Description 



angle Specifies in degrees the angle of the halftone screen. 

frequency Specifies in dots per inch of the screen frequency. 

types Is a mask containing bits which indicate the type of screen cell. If a 

pointer to this structure is passed as the lpInData parameter, only 
one bit may be set. If the lpOutData parameter contains a pointer to 
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this structure, when the escape returns, the types field will have a 
bit set for each type supported by the printer driver. Acceptable bit 
values are: 

□ DIAMOND 
a DOT 
a ELLIPSE 
a LINE 



Syntax short Escape(hDC, GETTECHNOLOGY, NULL, NULL, lpTechnology) 

This escape retrieves the general technology type for a printer, thereby 
allowing an application to perform technology-specific actions. 



Parameters hDC 



Return value 



HDC Identifies the device context. 



lpTechnology LPSTR Points to a buffer to which the driver copies a null- 
terminated string containing the printer technology type, 
such as "PostScript." 

The return value specifies the outcome of the escape. It is 1 if the escape is 
successful, and is zero if the escape is not successful or is not 
implemented. 



GETTRACKKERNTABLE 



Syntax short Escape(hDC, GETTRACKKERNTABLE, NULL, NULL, lpOutData) 

This escape fills the buffer pointed to by the lpOutData parameter with the 
track-kerning table for the currently selected font. 



Parameters hDC 



Return value 



HDC Identifies the device context. 

IpOutdata KERNTRACK FAR * Points to an array of KERNTRACK 

structures. This array must be large enough to accommodate 
all the font's kerning tracks. The number of tracks in the font 
can be obtained from the EXTTEXTMETRIC structure 
returned by the GETEXTENDEDTEXTMETRICS escape. See 
the following "Comments" section for the format of the 
KERNTRACK data structure. 

The return value specifies the number of KERNTRACK structures copied 
to the buffer. This value is zero if the font does not have kerning tracks 
defined, or if the escape fails or is not implemented. 



Chapter 12, Printer escapes 



181 



GETTRACKKERNTABLE 



Comments The KERNTRACK data structure has the following format: 



typedef struct { 



short 
short 
short 
short 
short 



ktDegree; 

ktMinSize; 

ktMinAraount; 

ktMaxSize; 

ktMaxAmount; 



KERNTRACK; 



The KERNTRACK structure contains the following fields: 



Field 



Description 



ktDegree Specifies the amount of track kerning. Increasingly negative 

values represent tighter track kerning, and increasingly positive 

values represent looser track kerning. 
ktMinSize Specifies in device units the minimum font size for which linear 

track kerning applies. 
ktMinAmount Specifies in font units the amount of track kerning to apply to 

font sizes less than or equal to the size specified by the ktMinSize 

field. 
ktMaxSize Specifies in device units the maximum font size for which linear 

track kerning applies. 
ktMaxAmount Specifies in font units the amount of track kerning to apply to 

font sizes greater than or equal to the size specified by the 

ktMaxSize field. 

Between the ktMinSize and ktMaxSize font sizes, track kerning is a linear 
function from ktMinAmount to ktMaxAmount. The values returned in the 
KERNTRACK structures are affected by whether relative character widths 
are enabled or disabled. For more information, see the description of the 
ENABLERELATIVEWIDTHS escape earlier in this chapter. 



GETVECTORBRUSHSIZE 



Syntax short Escape(hDC, GETVECTORBRUSHSIZE, sizeof(LOGBRUSH), 
lpInData, lpOutData) 

This escape retrieves in device units the size of a plotter pen used to fill 
closed figures. GDI uses this information to prevent the plotter pen from 
writing over the borders of the figure when filling closed figures. 

Parameters hDC HDC Identifies the device context. 

lpInData LOGBRUSH FAR * Points to a LOGBRUSH data structure 
that specifies the brush for which data are to be returned. 
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LPPOINT Points to a POINT data structure that contains in its 
second word the width of the pen in device units. 



Return value The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful or is not implemented. 



GETVECTORPENSIZE 



Syntax short Escape(hDC, GETVECTORPENSIZE, sizeof(LOGPEN), lpInData, 
IpOutData) 

This escape retrieves the size in device units of a plotter pen. GDI uses this 
information to prevent hatched brush patterns from overwriting the 
border of a closed figure. 



Parameters hDC 



Return value 



HDC Identifies the device context. 



lpInData LOGPEN FAR * Points to a LOGPEN data structure that 

specifies the pen for which the width is to be retrieved. 

IpOutData LPPOINT Points to a POINT data structure that contains in its 
second word the width of the pen in device units. 

The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful or if it is not 
implemented. 



MFCOMMENT 



Syntax BOOL Escape(hDC, MFCOMMENT, nCount, lpComment, NULL) 
This escape adds a comment to a metafile. 



Parameters hDC 



nCount 



Return value 



lpComment 



HDC Identifies the device context for the device on which 
the metafile appears. 

short Specifies the number of characters in the string 
pointed to by the lpComment parameter. 

LPSTR Points to a string that contains the comment that will 
appear in the metafile. 



The return value specifies the outcome of the escape. It is -1 if an error 
such as insufficient memory or an invalid port specification occurs. 
Otherwise, it is positive. 
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NEWFRAME 



Syntax short Escape(hDC, NEWFRAME, NULL, NULL, NULL) 

This escape informs the device that the application has finished writing to 
a page. This escape is typically used with a printer to direct the device 
driver to advance to a new page. 



Parameters 
Return value 



Comments 



hDC 



HDC Identifies the device context. 



The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is one of the following values: 

Value Meaning 



SP_APPABORT 

SP_ERROR 
SPJDUTOFDISK 

SP_OUTOFMEMORY 
SP USERABORT 



Job was terminated because the application's abort 

function returned zero. 

General error. 

Not enough disk space is currently available for spooling, 

and no more space will become available. 

Not enough memory is available for spooling. 

User terminated the job through the Print Manager. 



Do not use the NEXTBAND escape with NEWFRAME. For banding drivers, 
GDI replays a metafile to the printer, simulating a sequence of NEXTBAND 
escapes. 

The NEWFRAME escape restores the default values of the device context. 
Consequently, if a font other than the default font is selected when the 
application calls the NEWFRAME escape, the application must select the 
font again following the NEWFRAME escape. 



NEXTBAND 



Syntax short Escape(hDC, NEXTBAND, NULL, NULL, lpBandRect) 

This escape informs the device driver that the application has finished 
writing to a band, causing the device driver to send the band to the Print 
Manager and return the coordinates of the next band. Applications that 
process banding themselves use this escape. 

Parameters hDC HDC Identifies the device context. 

lpBandRect LPRECT Points to the RECT data structure that will receive 
the next band coordinates. The device driver copies the 
device coordinates of the next band into this structure. 
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Return value 



The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is one of the following values: 



Value 



Meaning 



SP APPABORT 



SP_ERROR 

SP OUTOFDISK 



Job was terminated because the application's abort 

function returned zero. 

General error. 

Not enough disk space is currently available for spooling, 

and no more space will become available. 
SP_OUTOFMEMORY Not enough memory is available for spooling. 
SPJJSERABORT User terminated the job through the Print Manager. 

Comments The NEXTBAND escape sets the band rectangle to the empty rectangle 
when printing reaches the end of a page. 

Do not use the NEWFRAME escape with NEXTBAND. 



PASSTHROUGH 



Syntax short Escape(hDC, PASSTHROUGH, nCount, lpInData, NULL) 

This escape allows the application to send data directly to the printer, 
bypassing the standard print-driver code. 

tz> To use this escape, an application must have thorough knowledge of how 
the particular printer operates. 



Parameters hDC 

nCount 



lpInData 



HDC Identifies the device context. 

short Specifies the number of bytes to which the lpInData 
parameter points. 

LPSTR Points to a structure whose first word (16 bits) 
contains the number of bytes of input data. The remaining 
bytes of the structure contain the data itself. 

Return value The return value specifies the number of bytes transferred to the printer if 
the escape is successful. It is less than zero if the escape is not 
implemented, and less than or equal to zero if the escape is not successful. 

Comments There may be restrictions on the kinds of device data an application can 
send to the device without interfering with the operation of the driver. In 
general, applications must avoid resetting the printer or causing the page 
to be printed. 

It is strongly recommended that applications not perform functions that 
consume printer memory, such as downloading a font or a macro. 
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An application can avoid corrupting its data stream when issuing 
multiple, consecutive PASSTHROUGH escapes if it does not access the 
printer any other way during the sequence. 



QUERYESCSUPPORT 



Syntax short Escape(hDC, QUERYESCSUPPORT, sizeof(int), IpEscNum, NULL) 

This escape determines whether a particular escape is implemented by the 
device driver. 



Parameters hDC 



HDC Identifies the device context. 



IpEscNum LPINT Points to a short-integer value that specifies the 
escape function to be checked. 

Return value The return value specifies whether a particular escape is implemented. It 
is nonzero for implemented escape functions. Otherwise, it is zero. 

If the IpEscNum parameter is set to DRAWPATTERNRECT, the return 
value is one of the following: 



Value 



Meaning 



DRAWPATTERNRECT is not implemented. 

1 DRAWPATTERNRECT is implemented for a printer other than the 
HP LaserJet IIP; this printer supports white rules. 

2 DRAWPATTERNRECT is implemented for the HP LaserJet IIP. 



RESTORE CTM 



Syntax short Escape(hDC, RESTORE_CTM, NULL, NULL, NULL) 

This escape restores the previously saved current transformation matrix. 

The current transformation matrix controls the manner in which 
coordinates are translated, rotated, and scaled by the device. By using 
matrices, an application can combine these operations in any order to 
produce the desired mapping for a particular picture. 

Parameters hDC HDC Identifies the device context. 

Return value The return value specifies the number of SAVE_CTM escape calls without 
a corresponding RESTORE_CTM call. If the escape is unsuccessful, the 
return value is — 1. 
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Comments Applications should not make any assumptions about the initial contents 
of the current transformation matrix. 

This escape uses a matrix specification based on the Microsoft OS/2 
Presentation Manager graphics programming interface (GPI) model, 
which is an integer-coordinate system similar to the system which GDI 
uses. 



SAVE CTM 



Syntax short Escape(hDC, SAVE_CTM, NULL, NULL, NULL) 

This escape saves the current transformation matrix. 
The current transformation matrix controls the manner in which 
coordinates are translated, rotated, and scaled by the device. By using 
matrices, an application can combine these operations in any order to 
produce the desired mapping for a particular picture. 

An application can restore the matrix by using the RESTORE_CTM 
escape. 

An application typically saves the current transformation matrix before 
changing it. This allows the application to restore the previous state upon 
completion of a particular operation. 

Parameters hDC HDC Identifies the device context. 

Return value The return value specifies the number of SAVE_CTM escape calls without 
a corresponding RESTORE_CTM call. The return value is zero if the 
escape was unsuccessful. 

Comments Applications should not make any assumptions about the initial contents 
of the current transformation matrix. 

Applications are expected to restore the contents of the current 
transformation matrix. 

This escape uses a matrix specification based on the OS/2 Presentation 
Manager graphics programming interface (GPI) model, which is an 
integer-coordinate system similar to the system that GDI uses. 
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SELECTPAPERSOURCE 



This escape has been superseded by the GETSETPAPERBINS escape and 
is provided only for backward compatibility. New applications should 
use the GETSETPAPERBINS escape instead. 



SETABORTPROC 



Syntax short Escape(hDC, SETABORTPROC, NULL, lpAbortFunc, NULL) 

This escape sets the abort function for the print job. 

If an application is to allow the print job to be canceled during spooling, it 
must set the abort function before the print job is started with the 
STARTDOC escape. Print Manager calls the abort function during 
spooling to allow the application to cancel the print job or to process out- 
of-disk-space conditions. If no abort function is set, the print job will fail if 
there is not enough disk space for spooling. 



Parameters hDC 



Return value 
Comments 



Callback 
Function 



HDC Identifies the device context. 



lpAbortFunc FARPROC Points to the application-supplied abort function. 
See the following "Comments" section for details. 

The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 

The address passed as the lpAbortFunc parameter must be created by 
using the MakeProclnstance function. 

The callback function must use the Pascal calling convention and must be 
declared FAR. The abort function must have the following form: 

short FAR PASCAL AbortFuncQiPr , code) 
HDC hPr; 
short code; 

AbortFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application's module-definition file. 



Parameters hPr 

code 



Identifies the device context. 

Specifies whether an error has occurred. It is zero if no error 
has occurred. It is SP_OUTOFDISK if Print Manager is 
currently out of disk space and more disk space will become 
available if the application waits. 
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If code is SP_OUTOFDISK, the application does not have to abort the print 
job. If it does not, it must yield to Print Manager by calling the 
PeekMessage or GetMessage function. 

Return value The return value should be nonzero if the print job is to continue, and 
zero if it is canceled. 



SETALLJUSTVALUES 

Syntax short Escape(hDC, SETALLJUSTVALUES, 

sizeof (JUST_VALUE_STRUCT), lpInData, NULL) 

This escape sets all of the text-justification values that are used for text 
output. 

Text justification is the process of inserting extra pixels among break 
characters in a line of text. The blank character is normally used as a break 
character. 

Parameters hDC 



Return value 



Comments 



lpInData 



HDC Identifies the device context. 

JUST_VALUE_STRUCT FAR * Points to a 
JUST_VALUE_STRUCT data structure that defines the text- 
justification values. See the following "Comments" section 
for more information on the JUST_VALUE_STRUCT data 
structure. 

The return value specifies the outcome of the escape. It is 1 if the escape is 
successful. Otherwise, it is zero. 

The lpInData parameter points to a JUST_VALUE_STRUCT data structure 
that describes the text-justification values used for text output. The 
JUST_VALUE_STRUCT structure has the following format: 

typedef struct { 

short nCharExtra; 

WORD nCharCount; 

short nBreakExtra; 

WORD nBreakCount; 
} JUST_VALUE_STRUCT; 

This structure has the following fields: 



Field 



Description 



nCharExtra Specifies the total extra space (in font units) that must be 

distributed over nCharCount characters. 
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nCharCount Specifies the number of characters over which nCharExtra is 

distributed. 
nBreakExtra Specifies the total extra space (in font units) that is distributed 

over nBreakCount characters. 
nBreakCount Specifies the number of break characters over which 

nBreakExtra is distributed. 

The units used for nCharExtra and nBreakExtra are the font units of the 
device and are dependent on whether relative character widths were 
enabled with the ENABLERELATIVEWIDTHS escape. 

The values set with this escape apply to subsequent calls to the TextOut 
function. The driver stops distributing the extra space specified in the 
nCharExtra field when it has output the number of characters specified in 
the nCharCount field. Likewise, it stops distributing the space specified by 
the nBreakExtra field when it has output the number of characters 
specified by the nBreakCount field. A call on the same string to the 
GetTextExtent function made immediately after the call to the TextOut 
function will be processed in the same manner. 

To re-enable justification with the SetTextJustification and 
SetTextCharacterExtra functions, an application should call the 
SETALLJUSTVALUES escape and set the nCharExtra and nBreakExtra 
fields to zero. 



SET ARC DIRECTION 



Syntax short Escape(hDC, SET_ARC_DIRECTION, sizeof(int), lpDirection, 
NULL) 

This escape specifies the direction in which elliptical arcs are drawn using 
the GDI Arc function. 

By convention, elliptical arcs are drawn counterclockwise by GDI. This 
escape lets an application draw paths containing arcs drawn clockwise. 

Parameters hDC HDC Identifies the device context. 

lpDirection LPINT Points to a short integer specifying the arc direction. It 
can be either of the following values: 

■ COUNTERCLOCKWISE (0) 

■ CLOCKWISE (1) 

Return value The return value is the previous arc direction. 

Comments This escape maps to PostScript language elements and is intended for 
PostScript line devices. 
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SET BACKGROUND COLOR 



Syntax 



short Escape(hDC, SET_BACKGROUND_COLOR, nCount, lpNewColor, 
lpOldColor) 

This escape sets and retrieves the current background color for the device. 

The background color is the color of the display surface before an 
application draws anything on the device. This escape is particularly 
useful for color printers and film recorders. 

This escape should be sent before the application draws anything on the 
current page. 



Parameters 



hDC HDC Identifies the device context. 

nCount int Specifies the number of bytes pointed to by the 

lpNewColor parameter. 

lpNewColor DWORD FAR * Points to a 32-bit integer specifying the 

desired background color. This parameter can be NULL if 
the application is merely retrieving the current background 
color. 

lpOldColor DWORD FAR * Points to a 32-bit integer which receives the 
previous background color. This parameter can be NULL if 
the application does not use the previous background color. 

Return value The return value is TRUE if the escape was successful and FALSE if it was 
unsuccessful. 

Comments The default background color is white. 

The background color is reset to the default when the device driver 
receives an ENDDOC or ABORTDOC escape. 



SET BOUNDS 



Syntax short Escape(hDC, SET_BOUNDS, sizeof(RECT), lpInData, NULL) 

This escape sets the bounding rectangle for the picture being produced by 
the device driver supporting the given device context. It is used when 
creating images in a file format such as Encapsulated PostScript (EPS) and 
Hewlett-Packard Graphics Language (HPGL) for which there is a device 
driver. 



Parameters hDC 



HDC Identifies the device context. 
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IpInData LPRECT Points to a RECT data structure that specifies in 

device coordinates a rectangle that bounds the image to be 
output. 

Return value The return value is TRUE if the escape was successful; otherwise, the 
return value is FALSE. 

Comments An application should issue this escape before each page in the image. For 
single-page images, this escape should be issued immediately before the 
STARTDOC escape. 

When an application uses coordinate-transformation escapes, device 
drivers may not perform bounding box calculations correctly. When an 
application uses the SET_BOUNDS escape, the driver does not have to 
calculate the bounding box. 

Applications should always use this escape to ensure support for the 
Encapsulated PostScript (EPS) printing capabilities that will be built into 
future PostScript drivers. 



SET CLIP BOX 



Syntax short Escape(hDC, SET_CLIP_BOX, sizeof(RECT), IpInData, 
(LPSTR)NULL) 

This escape sets the clipping rectangle or restores the previous clipping 
rectangle. This escape is implemented by printer drivers that implement 
the coordinate-transformation escapes TRANSFORM_CTM, SAVE_CTM, 
and RESTORE_CTM. 

When an application calls a GDI output function, GDI calculates a 
clipping rectangle bounding the primitive and passes both the primitive 
and the clipping rectangle to the printer driver. The printer driver is 
expected to clip the primitive to the specified bounding rectangle. 
However, when an application uses the coordinate-transformation 
escapes, the clipping rectangle calculated by GDI is usually invalid. An 
application can use the SET_CLIP_BOX escape to specify the correct 
clipping rectangle when coordinate transformations are used. 



Parameters hDC 



IpClipBox 



HDC Identifies the device context. 

LPRECT Points to a RECT data structure containing the 
bounding rectangle of the clipping area. If IpClipBox is not 
NULL, the previous clipping rectangle is saved and the 
current clipping rectangle is set to the specified bounds. If 
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IpClipBox is NULL, the previous clipping rectangle is 
restored. 

Return value The return value is TRUE if the clipping rectangle was properly set. 
Otherwise, it is FALSE. 



SETCOLORTABLE 

Syntax short Escape(hDC, SETCOLORTABLE, sizeof(COLORTABLE_STRUCT), 
lpInData, lpColor) 

This escape sets an RGB color-table entry. If the device cannot supply the 
exact color, the function sets the entry to the closest possible 
approximation of the color. 



Parameters hDC 



lpInData 



HDC Identifies the device context. 

COLORTABLE_STRUCT FAR * Points to a 
COLORTABLE_STRUCT data structure that contains the 
index and RGB value of the color-table entry. See the 
following "Comments" section for more information on the 
COLORTABLE STRUCT data structure. 



lpColor 



DWORD FAR * Points to the long-integer value that is to 
receive the RGB color value selected by the device driver to 
represent the requested color value. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 

Comments The COLORTABLE_STRUCT data structure has the following format: 

typedef struct { 

WORD Index; 

DWORD rgb; 
} COLORTABLE_STRUCT; 

This structure has the following fields: 



Field 



Description 



Index Specifies the color-table index. Color-table entries start at zero for the 

first entry. 
rgb Specifies the desired RGB color value. 

A device's color table is a shared resource; changing the system display 
color for one window changes it for all windows. Only applications 
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developers who have a thorough knowledge of the display driver should 
use this escape. 

The SETCOLORTABLE escape has no effect on devices with fixed color 
tables. 

This escape is intended for use by both printer and display drivers. 
However, the EGA and VGA color drivers do not support it. 

This escape changes the palette used by the display driver. However, since 
the driver's color-mapping algorithms will probably no longer work with 
a different palette, an extension has been added to this function. 

If the color index pointed to by the IpInData parameter is OXFFFF, the 
driver is to leave all color-mapping functionality to the calling application. 
The application must use the proper color-mapping algorithm and take 
responsibility for passing the correctly mapped physical color to the 
driver (instead of the logical RGB color) in such device-driver functions as 
RealizeObject and Colorlnfo. 

For example, if the device supports 256 colors with palette indexes of 
through 255, the application would determine which index contains the 
color that it wants to use in a certain brush. It would then pass this index 
in the low-order byte of the DWORD logical color passed to the 
RealizeObject device-driver function. The driver would then use this 
color exactly as passed instead of performing its usual color-mapping 
algorithm. If the application wants to reactivate the driver's color- 
mapping algorithm (that is, if it restores the original palette when 
switching from its window context), then the color index pointed to by 
IpInData should be OxFFFE. 



SETCOPYCOUNT 



Syntax short Escape(hDC, SETCOPYCOUNT, sizeof(int), lpNumCopies, 
lpActualCopies) 

This escape specifies the number of uncollated copies of each page that 
the printer is to print. 

Parameters hDC HDC Identifies the device context. 

lpNumCopies LPINT Points to a short-integer value that contains the 
number of uncollated copies to be printed. 

lpActualCopies LPINT Points to a short-integer value that will receive the 
number of copies to be printed. This may be less than the 
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number requested if the requested number is greater than 
the device's maximum copy count. 

Return value The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 



SETKERNTRACK 



Syntax short Escape(hDC, SETKERNTRACK, sizeof(int), lpNewTrack, 
lpOldTrack) 

This escape specifies which kerning track to use for drivers that support 
automatic track kerning. A kerning track of zero disables automatic track 
kerning. 

When track kerning is enabled, the driver will automatically kern all 
characters according to the specified track. The driver will reflect this 
kerning both on the printer and in GetTextExtent function calls. 



Parameters hDC 



lpNewTrack 



lpOldTrack 



HDC Identifies the device context. 

LPINT Points to a short-integer value that specifies the 
kerning track to use. A value of zero disables this feature. 
Values in the range 1 to nKernTracks correspond to positions 
in the track-kerning table (using 1 as the first item in the 
table). For more information, see the description of the 
EXTTEXTMETRIC structure provided under the description 
of the GETEXTENDEDTEXTMETRICS escape. 

LPINT Points to a short-integer value that will receive the 
previous kerning track. 



Return value 



The return value specifies the outcome of the escape. It is 1 if the escape is 
successful; it is zero if the escape is not successful or not implemented. 

Comments Automatic track kerning is disabled by default. 

A driver does not have to support the ENABLEPAIRKERNING escape just 
because it supplies the track-kerning table to the application by using the 
GETTRACKKERNTABLE escape. In the case where 
GETTRACKKERNTABLE is supported but the SETKERNTRACK escape is 
not, the application must properly space the characters on the output 
device. 



Chapter 12, Printer escapes 



195 



SETLINECAP 



SETUNECAP 



Syntax short Escape(hDC, SETLINECAP, sizeof (int), lpNewCap, lpOldCap) 

This escape sets the line end cap. 

A line end cap is that portion of a line segment that appears on either end 
of the segment. The cap may be square or circular. It can extend past, or 
remain flush with the specified segment end points. 



Parameters hDC 



Return value 



Comments 



SETUNEJOIN 



IpNezvCap 



HDC Identifies the device context. 

LPINT Points to a short-integer value that specifies the end- 
cap type. The possible values and their meanings are given 
in the following list: 

■ -1 Line segments are drawn by using the default GDI end 
cap. 

■ Line segments are drawn with a squared end point that 
does not project past the specified segment length. 

b 1 Line segments are drawn with a rounded end point; the 
diameter of this semicircular arc is equal to the line width. 

b 2 Line segments are drawn with a squared end point that 
projects past the specified segment length. The projection 
is equal to half the line width. 

LPINT Points to a short-integer value that specifies the 
previous end-cap setting. 

The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 

The interpretation of this escape varies with page-description languages 
(PDLs). Consult the PDL documentation for its exact meaning. 

This escape is also known as SETENDCAP. 



lpOldCap 



Syntax short Escape(hDC, SETLINEJOIN, sizeof (int), lpNewJoin, lpOldJoin) 

This escape specifies how a device driver will join two intersecting line 
segments. The intersection can form a rounded, squared, or mitered 
corner. 



Parameters hDC 



HDC Identifies the device context. 
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IpNewJoin LPINT Points to a short-integer value that specifies the type 
of intersection. The possible values and their meanings are 
given in the following list: 

□ -1 Line segments are joined by using the default GDI 
setting. 

□ Line segments are joined with a mitered corner; the 
outer edges of the lines extend until they meet at an angle. 
This is referred to as a miter join. 

□ 1 Line segments are joined with a rounded corner; a 
semicircular arc with a diameter equal to the line width is 
drawn around the point where the lines meet. This is 
referred to as a round join. 

a 2 Line segments are joined with a squared end point; the 
outer edges of the lines are not extended. This is referred 
to as a bevel join. 

IpOldJoin LPINT Points to a short-integer value that specifies the 
previous line join setting. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 

Comments The interpretation of this escape varies with page-description languages 
(PDLs). Consult the PDL documentation for its exact meaning. 

If an application specifies a miter join but the angle of intersection is too 
small, the device driver ignores the miter setting and uses a bevel join 
instead. 



SET MIRROR MODE 



Syntax short Escape(hDC, SET_MIRROR_MODE, sizeof(WORD), lpInData, 
(LPSTR)NULL) 

This escape sets the current mirror mode. The mirror mode produces 
mirror images along the horizontal axis, the vertical axis, or both axes. 

To produce a mirror image of a given page, the application issues the 
SET_MIRROR_MODE escape before drawing the first primitive to be 
mirrored. When the last mirrored primitive has been drawn, the 
application issues a second SET_MIRROR_MODE escape to turn off 
mirroring. 



Parameters hDC 



HDC Identifies the device context. 
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Return value 
Comments 



IpMirrorMode LPINT Points to a short integer that specifies the mirror 
mode. It must be one of the following values: 

■ MIRROR_NONE (0) Disable mirroring. 

■ MIRROR_HORIZONTAL (1) Mirror along the 
horizontal axis. 

■ MIRROR_VERTICAL (2) Mirror along the vertical axis. 
b MIRROR_BOTH (3) Mirror along both axes. 

The return value is the previous mirror mode. 

The default mirror mode is MIRROR_NONE. 

Mirrored and unmirrored output can be mixed on a page. This allows the 
application to produce mirrored output with unmirrored page labels, crop 
marks, and so on. 



SETMITERUMIT 



Syntax short Escape(hDC, SETMITERUMIT, sizeof(int), lpNewMiter, lpOldMiter) 

This escape sets the miter limit for a device. The miter limit controls the 
angle at which a device driver replaces a miter join with a bevel join. 



Parameters 



hDC 
nCount 



HDC Identifies the device context. 



short Specifies the number of bytes to which the lpNewMiter 
parameter points. 

lpNewMiter LPINT Points to a short-integer value that specifies the 

desired miter limit. Only values greater than or equal to -1 
are valid. If this value is -1, the driver will use the default 
GDI miter limit. 

lpOldMiter LPINT Points to a short-integer value that specifies the 
previous miter-limit setting. 

Return value The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 

Comments The miter limit is defined as follows: 

miter length 1 



line width sin(x/2) 

X is the angle of the line join in radians. 

The interpretation of this escape varies with page-description languages 
(PDLs). Consult the PDL documentation for its exact meaning. 
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SET POLY MODE 



Syntax short EscapeChDC, SET_POLY_MODE, sizeof(int), IpMode, NULL) 

This escape sets the poly mode for the device driver. The poly mode is a 
state variable indicating how to interpret calls to the GDI Polygon and 
Polyline functions. 

The SET_POLY_MODE escape enables a device driver to draw shapes 
(such as Bezier curves) not supported directly by GDI. This permits 
applications that draw complex curves to send the curve description 
directly to a device without having to simulate the curve as a polygon 
with a large number of points. 



Parameters HDC 

IpMode 



HDC Identifies the device context. 

LPINT Points to a short integer specifying the desired poly 
mode. The poly mode is a state variable indicating how 
points in Polygon or Polyline function calls should be 
interpreted. All device drivers are not required to support 
all possible modes. A device driver returns zero if it does not 
support the specified mode. The IpMode parameter may be 
one of the following values: 

p PM_POLYLINE (1) The points define a conventional 
polygon or polyline. 

□ PM_BEZIER (2) The points define a sequence of 4-point 
Bezier spline curves. The first curve passes through the 
first four points, with the first and fourth points as end 
points, and the second and third points as control points. 
Each subsequent curve in the sequence has the end point 
of the previous curve as its start point, the next two points 
as control points, and the third as its end point. 

The last curve in the sequence is permitted to have fewer 
than four points. If the curve has only one point, it is 
considered a point. If it has two points, it is a line segment. 
If it has three points, it is a parabola defined by drawing a 
Bezier curve with the first and third points as end points 
and the two control points equal to the second point. 

□ PM_POLYLINESEGMENT (3) The points specify a list of 
coordinate pairs. Line segments are drawn connecting 
each successive pair of points. 

n PM_POLYSCANLINE (4) The points specify a list of 
coordinate pairs. Line segments are drawn connecting 
each successive pair of points. Each line segment is a 
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Return value 



Comments 



nominal-width line drawn using the current brush. Each 
line segment must be strictly vertical or horizontal, and 
scan lines must be passed in strictly increasing or 
decreasing order. This mode is only used for polygon calls. 

The return value is the previous poly mode. If the return value is zero, the 
device driver did not handle the request. 

An application should issue the SET_POLY_MODE escape before it draws 
a complex curve. It should then call the Polyline or Polygon function with 
the desired control points defining the curve. After drawing the curve, the 
application should reset the driver to its previous state by issuing the 
SET_POLY_MODE escape. 

Polyline calls draw using the currently selected pen. 

Polygon calls draw using the currently selected pen and brush. If the start 
and end points are not equal, a line is drawn from the start point to the 
end point before filling the polygon (or curve). 

GDI treats Polygon calls using PM_POLYLINESEGMENT mode exactly 
the same as Polyline calls. 

Four points define a Bezier curve. GDI generates the curve by connecting 
the first and second, second and third, and third and fourth points. GDI 
then connects the midpoints of these consecutive line segments. Finally, 
GDI connects the midpoints of the lines connecting the midpoints, and so 
forth. 

The line segments drawn in this way converge to a curve defined by the 
following parametric equations, expressed as a function of the 
independent variable t . 

X(t) = (1-f) 3 ^ + 3{\-t) 2 tx 2 + 3(l-t)t 2 x 3 + t 3 x 4 

Y(t) = (1-0 3 !/! + 3{\-t) 2 ty 2 + 3(l-t)t 2 y 3 + thj^ 

The points (x^y-^, (x 2 ,y 2 ), (x 3 ,y 3 ) and (x 4 ,y 4 ) are the control points defining 
the curve. The independent variable t varies from to 1 . 

The points (Cx 1 ,Cy 1 ) and (Cx 2 ,Cy 2 ) are third-degree control points of a 
second-degree Bezier curve specified by the points (X 1 ,Y 1 ), (X 2 ,Y 2 ), and 
(X 3 ,Y 3 ). 

Primitive types other than PM_BEZIER and PM_POLYLINESEGMENT 
may be added to this escape in the future. Applications should check the 
return value from this escape to determine whether or not the driver 
supports the specified poly mode. 
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SET SCREEN ANGLE 



Syntax short Escape(hDC, SET_SCREEN_ANGLE, sizeof (int), lp Angle, NULL) 

This escape sets the current screen angle to the desired angle and enables 
an application to simulate the tilting of a photographic mask in producing 
a color separation for a particular primary. 



Parameters hDC 



Return value 
Comments 



IpAngle 



HDC Identifies the device context. 

LPINT Points to a short-integer value specifying the desired 
screen angle in tenths of a degree. The angle is measured 
counterclockwise. 



The return value is the previous screen angle. 

Four-color process separation is the process of separating the colors 
comprising an image into four component primaries: cyan, magenta, 
yellow, and black. The image is then reproduced by overprinting each 
primary. 

In traditional four-color process printing, half-tone images for each of the 
four primaries are photographed against a mask tilted to a particular 
angle. Tilting the mask in this manner minimizes unwanted moire 
patterns caused by overprinting two or more colors. 

The device driver defines the default screen angle. 



SET SPREAD 



Syntax short Escape(hDC, SET_SPREAD, sizeof(int), IpSpread, NULL) 

This function sets the amount that nonwhite primitives are expanded for a 
given device to provide a slight overlap between primitives to 
compensate for imperfections in the reproduction process. 

Spot color separation is the process of separating an image into each 
distinct color used in the image. The image is reproduced by overprinting 
each successive color in the image. 

When reproducing a spot-separated image, the printing equipment must 
be calibrated to align each page exactly on each pass. However, 
differences in temperature, humidity, and so forth, between passes often 
cause images to align imperfectly on subsequent passes. For this reason, 
lines in spot separations are often widened (spread) slightly to make up 
for problems in registering subsequent passes through the printer. This 
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process is called trapping. The SET_SPREAD escape implements this 
process. 

Parameters hDC HDC Identifies the device context. 

IpSpread LPINT Points to a short-integer value that specifies the 

amount, in pixels, by which all nonwhite primitives are to be 
expanded. 

Return value The return value is the previous spread value. 

Comments The default spread is zero. 

The current spread applies to all bordered primitives (whether or not the 
border is visible) and text. 



STARTDOC 



Syntax short Escape(hDC, STARTDOC, nCount, lpDocName, NULL) 

This escape informs the device driver that a new print job is starting and 
that all subsequent NEWFRAME escape calls should be spooled under the 
same job until an ENDDOC escape call occurs. This ensures that 
documents longer than one page will not be interspersed with other jobs. 



Parameters hDC 

nCount 



lpDocName 



HDC Identifies the device context. 

short Specifies the number of characters in the string 
pointed to by the lpDocName parameter. 

LPSTR Points to a null-terminated string that specifies the 
name of the document. The document name is displayed in 
the Print Manager window. The maximum length of this 
string is 31 characters plus the terminating null character. 

Return value The return value specifies the outcome of the escape. It is -1 if an error 
such as insufficient memory or an invalid port specification occurs. 
Otherwise, it is positive. 

Comments The correct sequence of events in a printing operation is as follows: 

1. Create the device context. 

2. Set the abort function to keep out-of-disk-space errors from 
terminating a printing operation. 

An abort procedure that handles these errors must be set by using the 
SETABORTPROC escape. 

3. Begin the printing operation with the STARTDOC escape. 
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4. Begin each new page with the NEWFRAME escape, or each new band 
with the NEXTBAND escape. 

5. End the printing operation with the ENDDOC escape. 

6. Destroy the cancel dialog box, if any. 

7. Free the procedure-instance address of the abort function. 

If an application encounters a printing error or a canceled print operation, 
it must not attempt to terminate the operation by using the Escape 
function with either the ENDDOC or ABORTDOC escape. GDI 
automatically terminates the operation before returning the error value. 



TRANSFORM CTM 



Syntax short Escape(hDC, TRANSFORM_CTM, 36, lpMatrix, NULL) 

This escape modifies the current transformation matrix. The current 
transformation matrix controls the manner in which coordinates are 
translated, rotated, and scaled by the device. By using matrices, you can 
combine these operations in any order to produce the desired mapping 
for a particular picture. 

The new current transformation matrix will contain the product of the 
matrix referenced by the lpMatrix parameter and the previous current 
transformation matrix (CTM = M " CTM). 



Parameters hDC 



Return value 



Comments 



HDC Identifies the device context. 

lpMatrix LPSTR Points to a 3-by-3 array of 32-bit integer values 

specifying the new transformation matrix. Entries in the 
matrix are scaled to represent fixed-point real numbers. Each 
matrix entry is scaled by 65,536. The high-order word of the 
entry contains the whole integer portion, and the low-order 
word contains the fractional portion. 

The return value is TRUE if the escape was successful and FALSE if it was 
unsuccessful. 

When an application modifies the current transformation matrix, it must 
specify the clipping rectangle by issuing the SET_CLIP_BOX escape. 

Applications should not make any assumptions about the initial value of 
the current transformation matrix. 
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The matrix specification used for this escape is based on the Microsoft 
OS/2 Presentation Manager graphics programming interface (GPI) model, 
which is an integer-coordinate system similar to the one used by GDI. 
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Windows DDE protocol definition 



The Microsoft Windows Dynamic Data Exchange (DDE) protocol defines 
the method for communicating among applications. This communication 
takes place as applications send messages to each other to initiate 
conversations, to request and share data, and to terminate conversations. 
This chapter describes these messages and the rules associated with their 
use. It also briefly describes several clipboard formats which a DDE 
application can register for use in a DDE conversation. 

Guide to Programming provides an overview of DDE programming, 
including such concepts as client, server, application, topic and item. It 
also introduces the modes of DDE communication, including permanent 
data links, one-time transfers, and remote command execution, and it 
explains the flow of DDE messages. 

Message-specific argument names bear prefixes indicating their type, as 
follows: 



Prefix 



Description 



a An atom of word length (16 bits); for example, aNatne. 

cf A registered clipboard format number (word length); for example, 

cfFormat. 
f A flag bit; for example, fName. 

h A handle (word length) to a global memory bject; for example, hName. 

w Any other word-length argument; for example, wName. 
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Each DDE message has two parameters. The first parameter, wParam 
(word length), carries the handle of the sender's window; it is the same in 
all cases and so is not shown in Table 13.1. The second parameter, IParam 
(a long word, 32 bits), is composed of a low-order word and a high-order 
word containing message-specific arguments, as follows: 

Table 13.1 
DDE messages 





Arguments in IParam 




Message 


Low-order word 


High-order word 


WM DDE ACK 






In reply to INITIATE 


aApplication 


aTopic 


In reply to EXECUTE 


wStatus 


hCommands 


All other messages 


wStatus 


altem 


WM DDE ADVISE 


hOptions 


altem 


WM DDE DATA 


hData 


altem 


WM DDE EXECUTE 


(Reserved) 


hCommands 


WM DDE INITIATE 


aApplication 


aTopic 


WM DDE POKE 


hData 


altem 


WM DDE REQUEST 


cfFormat 


altem 


WM DDE TERMINATE 


(Reserved) 


(Reserved) 


WM DDE UNADVISE 


(Reserved) 


altem 



An application calls the Send Message function to issue the 
WM_DDE_INITIATE message or a WM_DDE_ACK message sent in 
response to WM_DDE_INITIATE. All other messages are sent using the 
PostMessage function. The window handle of the receiving window 
appears as the first parameter of these calls. The second parameter 
contains the message to be sent, the third parameter identifies the sending 
window, and the fourth parameter contains the message-specific 
arguments. For example: 

PostMessage (hwndRecipient, WM_DDE_MESSAGE, hwndSender, 
MAKELONG(low_word, high_word) ) 

The MAKELONG macro combines low_word and highword into a long 
word. 



Synchronizing the DDE conversation 



An application window that processes DDE requests from the window of 
a DDE partner must process them strictly in the order in which they are 
received from that partner. However, when handling messages from 
multiple DDE partners, the window does not have to follow this "first in, 
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first out" rule. In other words, only the conversations themselves must be 
synchronous; the window can shift from one conversation to another 
asynchronously. 

For example, suppose the following messages are in a window's queue: 

Message from window X 
Message from window Y 
Message from window X 

The window must process message 1 before message 3, but it need not 
process message 2 before message 3. If window Y is a lower-priority 
DDE-conversation partner than window X, the window can defer 
processing the messages from window Y until it has finished dealing with 
the messages sent by window X. The following table shows acceptable 
processing orders for these messages and the relative priority implied by 
each order: 

Order Relative Priority 

12 3 Window X = window Y 

13 2 Window X > window Y 
2 13 Window X < window Y 

If an application is unable to process an incoming request because it is 
waiting for a DDE response, it must post a WM_DDE_ACK message with 
the fBusy flag set to 1 to prevent deadlock. An application can also send a 
busy WM_DDE_ACK message if for any reason the application cannot 
process an incoming request within a reasonable amount of time. 

An application should be able to deal with the situation in which its DDE 
partner fails to respond with a message within a certain time-out interval. 
Since the length of this interval may vary depending on the nature of the 
application and the configuration of the user's system (including whether 
it is on a network), the application should provide a way for the user to 
specify the time-out interval. 



Using atoms 



The section "DDE Certain arguments of DDE messages (altem, aTopic, and aApplication) are 

message directory" gi b a i a toms. Applications using these atoms must explicitly delete them 
describes the rules 

for allocating and to P ur 8 e them from the atom list - 

used bv each * n a ^ cases ' tne sender of a message must delete any atom which the 

message, intended receiver will not receive due to an error condition, such as 
failure of the PostMessage function. 
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Using shared memory objects 



"DDE message 

directory" on page 

40 describes the 

rules for allocating 

and deleting 

shared memory 

objects used by 

each message. 



DDE uses shared memory objects for three purposes: 

□ To carry a data item value to be exchanged. This is an item referenced 
by the hData argument in the WM_DDE_DATA and WM_DDE_POKE 
messages. 

□ To carry options in a message. This is an item referenced by the 
hOptions argument in a WM_DDE_ADVISE message. 

m To carry an execution-command string. This is an item referenced by 
the hCommands argument in the WM_DDE_EXECUTE message and its 
corresponding WMDDEACK message. 

Applications that receive a DDE shared memory object must treat it as 
read only. It must not be used as a mutual read/write area for the free 
exchange of data. 

As with a DDE atom, a shared memory object should be freed properly to 
provide for effective memory management. Shared memory objects 
should be properly locked and unlocked. 

In all cases, the sender of a message must delete any shared memory 
object which the intended receiver will not receive due to an error 
condition, such as failure of the PostMessage function. 



Using clipboard formats 



You can pass data by means of any of the standard clipboard formats or 
with a registered clipboard formats. See the description of the 
SetClipboardData function in Chapter 4, "Functions directory," in 
Reference, Volume 1, for more information on standard clipboards. See the 
description of the RegisterClipboardFormat function for information on 
registering clipboard formats. 

A special, registered format named Link is used to identify an item in a 
DDE conversation. For more information, see Guide to Programming. 



Using the System topic 



Applications are encouraged to support at all times a special topic with 
the name System. This topic provides a context for items of information 
that may be of general interest to another application. 
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The following list contains suggested items for the System topic. This list 
is not exclusive. The data item values should be rendered in the CFTEXT 
format. Individual elements of a System topic item value should be 
delimited by tab characters. 



Item 



Description 



Sysltems 
Topics 

ReturnMessage 



Status 



Formats 



A list of the System-topic items supported by the application. 
A list of the topics supported by the application at the current 
time; this list can vary from moment to moment. 
Supporting detail for the most recently used WM_DDE_ACK 
message. This is useful when more than eight bits of 
application-specific return data are required. 
An indication of the current status of the application. When a 
server receives a WM_DDE_REQUEST message for this 
System-topic item, it should respond by posting a 
WM_DDE_DATA message with a string containing either 
"Busy" or "Ready," as appropriate. 

A list of clipboard format numbers that the application can 
render. 



DDE message directory 



This section describes the nine DDE messages. Included in each 
description is a list of the message-specific arguments and the rules for 
posting and receiving each message. The SDK contains the DDE.H header 
file, which defines the DDE messages and data structures described in this 
section. 



WM DDE ACK 



This message notifies an application of the receipt and processing of a 
WM_DDEJNITIATE, WM_DDE_EXECUTE, WM_DDE_DATA, 
WM_DDE_ADVISE, WM_DDE_UNADVISE, or WM_DDE_POKE 
message, and in some cases, of a WM_DDE_REQUEST message. 



Parameter 



Description 



wParam 
IParam 



Identifies the sending window. 

The meaning of the low-order and high-order words 

depends on the message to which the WM_DDE_ACK 

message is responding. When responding to 

WM DDE INITIATE: 
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Comments 



Posting 



Argument 

aApplication 



aTopic 



Description 

Low-order word of IParam. An atom that 

contains the name of the replying 

application. 

High-order word of IParam. An atom that 

contains the topic with which the replying 

server window is associated. 



When responding to WM_DDE_EXECUTE: 

Argument Description 

wStatus Low-order word of IParam. A series of flags 

that indicate the status of the response. 

hCommands High-order word of IParam. A handle that 
identifies the data item containing the 
command string. 

When replying to all other messages: 

Argument Description 

wStatus Low-order word of IParam. A series of flags 

that indicate the status of the response. 

altem High-order word of IParam. An atom that 

specifies the data item for which the 
response is sent. 

The wStatus word consists of a DDEACK data structure that contains the 
following information: 



Bit 



Name 



Meaning 



15 
14 



13-8 
7-0 



fAck 



fBusy 



bAppReturnCode 



1 = Request accepted. 

= Request not accepted. 

1 = Busy. An application is expected to set fBusy 
if it is unable to respond to the request at the time 
it is received. The fBusy flag is defined only 
when fAck is zero. 

= Not busy. 

Reserved for Microsoft use. 

Reserved for application-specific return codes. 



Except in response to the WM_DDE_INLTIATE message, post the 
WM_DDE_ACK message by calling the PostMessage function, not 
SendMessage. When responding to WM_DDE_INITIATE, send the 
WM_DDE_ACK message with SendMessage. 

When acknowledging any message with an accompanying altem atom, the 
application that sends WM_DDE_ACK can reuse the altem atom that 
accompanied the original message, or it may delete it and create a new 
one. 
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WM DDE ACK 



When acknowledging WM_DDE_EXECUTE, the application that sends 
WM_DDE_ACK should reuse the hCommands object that accompanied the 
original WM_DDE_EXECUTE message. 

If an application has initiated the termination of a conversation by 
sending WM_DDE_TERMINATE and is awaiting confirmation, the 
waiting application should not acknowledge (positively or negatively) 
any subsequent message sent by the other application. The waiting 
application should delete any atoms or shared memory objects received in 
these intervening messages. 

Receiving The application that receives WM_DDE_ACK should delete all atoms 
accompanying the message. 

If the application receives WM_DDE_ACK in response to a message with 
an accompanying hData object, the application should delete the hData 
object. 

If the application receives a negative WM_DDE_ACK message sent in 
reply to a WM_DDE_ADVISE message, the application should delete the 
hOptions object sent with the original WM_DDE_ADV r ISE message. 

If the application receives a negative WMDDEACK message sent in 
reply to a WM_DDE_EXECUTE message, the application should delete 
the hCommands object sent with the original WM_DDE_EXECUTE 
message. 



WM DDE ADVISE 



This message, posted by a client application, requests the receiving 
(server) application to supply an update for a data item whenever it 
changes. 



Parameter Description 



wParam Identifies the sending window. 

IParam Identifies the requested data and specifies how the data is to be sent. 

Argument Description 

hOptions Low-order word of IParam. A handle to a global 

memory object that specifies how the data is to be 
sent. 

altem High-order word of IParam. An atom that specifies 

the data item being requested. 

Comments The global memory object identified by hOptions consists of a DDEADVISE 
data structure that contains the following: 
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Word 



Name 



Content 



1 f AckReq If bit 15 is 1, the receiving (server) application is 

requested to send its WM_DDE_DATA messages 
with the ACK-requested bit (f AckReq) set. This 
offers a flow-control technique whereby the client 
application can avoid overload from incoming 
DATA messages. 

f DeferUpd If bit 14 is 1, the server is requested to send its 

WM_DDE_DATA messages with a null hData 
handle. These messages are alarms telling the client 
that the source data has changed. Upon receiving 
one of these alarms, the client can choose to call for 
the latest version of the data by issuing a 
WM_DDE_REQUEST message, or it can choose to 
ignore the alarm altogether. This would typically be 
used when there is a substantial resource cost 
associated with rendering and /or assimilating the 
data. 

reserved Bits 13-0 are reserved. 

2 cf Format The client's preferred type of data. Must be a 

standard or registered clipboard data format 
number. 

If an application supports more than one clipboard format for a single 
topic and item, it can post multiple WM_DDE_ADVISE messages for the 
topic and item, specifying a different clipboard format with each message. 

Posting Post the WM_DDE_ADVISE message by calling the PostMessage 
function, not SendMessage. 

Allocate hOptions by calling the GlobalAlloc function with the 
GEMEM_DDE_SHARE option. 

Allocate altem by calling the Global Add Atom function. 

If the receiving (server) application responds with a negative 
WM_DDE_ACK message, the sending (client) application must delete the 
hOptions object. 

Receiving Post the WM_DDE_ACK message to respond positively or negatively. 
When posting WM_DDE_ACK, reuse the altem atom or delete it and 
create a new one. If the WM_DDE_ACK message is positive, delete the 
hOptions object; otherwise, do not delete the object. 
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WM DDE DATA 



This message, posted by a server application, sends a data item value to 
the receiving (client) application, or notifies it of the availability of data. 



Parameter Description 



wParam 
IParam 



Identifies the sending window. 

Identifies the available data and specifies how it is sent. 



Argument 

hData 



altem 



Description 

Low-order word of IParam. A handle that identifies 
the global memory object containing the data and 
additional information. The handle should be set to 
NULL if the server is notifying the client that the 
data item value has changed during a "warm link." 
A warm link is established by the client sending a 
WM_DDE_ADVISE message with the fDeferUpd bit 
set. 

High-order word of IParam. An atom that identifies 
the data item for which data or notification is sent. 



Comments The global memory object identified by hData consists of a DDEDATA data 
structure that contains the following: 



Word 



Name 



Content 



1 f AckReq If bit 15 is 1, the receiving (client) application is 

expected to send a WM_DDE_ACK message after 
the WM_DDE_DATA message has been processed. 
If bit 15 is zero, the client application should not 
send a WM_DDE_ACK message, 
reserved Bit 14 is reserved. 

f Release If bit 13 is 1, the client application is expected to free 

the hData memory object after processing it. If bit 13 
is zero, the client application should not free the 
object. See the "Posting" and "Receiving" sections for 
exceptions. 

f Requested If bit 12 is 1, this data is offered in response to a 

WM_DDE_REQUEST message. If bit 12 is zero, this 
data is offered in response to a WM_DDE_ADVISE 
message. 

reserved Bits 11-0 are reserved. 

2 cfFormat This specifies the format in which the data are sent 

or offered to the client application. It must be a 
standard or registered clipboard data format. 
3-n Value[ ] This is the data. It is in the format specified by 

cfFormat. 
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Posting Post the WM_DDE_DATA message by calling the PostMessage function, 
not SendMessage. 

Allocate hData by calling the GlobalAlloc function with the 
GMEM_DDESHARE option. 

Allocate altem by calling the Global Add Atom function. 

If the receiving (client) application responds with a negative 
WM_DDE_ACK message, the sending (server) application must delete the 
hData object. 

If the sending (server) application sets the f Release flag to zero, the 
sender is responsible for deleting hData upon receipt of either a positive or 
negative acknowledgement. 

Do not set both the f AckReq and f Release flags to zero. If both flags are 
set to zero, it is difficult for the sending (server) application to determine 
when to delete hData. 

Receiving If f AckReq is 1, post the WM_DDE_ACK message to respond positively or 
negatively. When posting WM_DDE_ACK, reuse the altem atom or delete 
it and create a new one. 

If f AckReq is zero, delete the altem atom. 

If the sending (server) application specified hData as NULL, the receiving 
(client) application can request the server to send the actual data by 
posting a WM_DDE_REQUEST message. 

After processing the WM_DDE_DATA message in which hData is not 
NULL, delete hData unless either of the following conditions is true: 

d The f Release flag is zero. 

b The f Release flag is 1, but the receiving (client) application responds 
with a negative WM_DDE_ACK message. 

WM_DDE_EXECUTE 

This message, posted by a client application, sends a string to a server 
application to be processed as a series of commands. The server 
application is expected to post a WM_DDE_ACK message in response. 



Parameter Description 



ivParam Identifies the sending window. 
IParam Specifies the commands to be executed. 
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Argument Description 

reserved The low-order word of IParam is reserved. 

hCommands High-order word of IParam. A handle that identifies 

a global memory object containing the command(s) 

to be executed. 



Comments The command string is null-terminated. The command string should 

adhere to the syntax shown below. Optional syntax elements are enclosed 
in double brackets ([[ ]]); single brackets ([ ]) are a syntax element. 

[opcodestring] [[ [opcodestring] ]] ... 

The opcodestring uses the following syntax: 

opcode[[ (parameter [[ parameter ]]...)]] 

The opcode is any application-defined single token. It may not include 
spaces, commas, parentheses, or quotation marks. 

The parameter is any application-defined value. Multiple parameters are 
separated by commas, and the entire parameter list is enclosed in 
parentheses. The parameter may not include commas or parentheses 
except inside a quoted string. If a bracket or parenthesis character is to 
appear in a quoted string, it must be doubled: ((. 

The following examples show valid command strings: 

[connect] [download (queryl, results. txt ) ] [disconnect] 
[query ("sales per employee for each district")] 
[open ("sample. xlm") ] [run("rlcl") ] 

Posting Post the WM_DDE_EXECUTE message by calling the PostMessage 
function, not SendMessage. 

Allocate hCommands by calling the GlobalAlloc function with the 
GMEM_DDE_SHARE option. 

When processing WM_DDE_ACK sent in reply to WM_DDE_EXECUTE, 
the sender of the original WM_DDE_EXECUTE message must delete the 
hCommands object sent back in the WM_DDE_ACK message. 

Receiving Post the WM_DDE_ACK message to respond positively or negatively, 
reusing the hCommands object. 
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WM DDE INITIATE 



This message, sent by either a client or server application, initiates a 
conversation with applications responding to the specified application 
and topic names. 

Upon receiving this message, all applications with names that match the 
aApplication application and that support the aTopic topic are expected to 
acknowledge it (see the WM_DDE_ACK message). 

Parameter Description 

wParam Identifies the sending window. 

iParam Specifies the target application and the topic. 

Argument Description 

aApplication Low-order word of IParam. An atom that 

specifies the name of the application with 
which a conversation is requested. The 
application name may not contain slashes or 
backslashes. These characters are reserved for 
future use in network implementations. If the 
application name is NULL, a conversation 
with all applications is requested. 

aTopic High-order word of IParam. An atom that 

specifies the topic for which a conversation is 
requested. If the topic is NULL, a 
conversation for all available topics is 
requested. 

Comments If the aApplication argument is NULL, any application may respond. If the 
aTopic argument is NULL, any topic is valid. Upon receiving a 
WM_DDE_INITIATE request with a null topic, an application is expected 
to send a WM_DDE_ACK message for each of the topics it supports. 

Sending Send the WM_DDE_INITIATE message by calling the SendMessage 
function, not the PostMessage function. Broadcast the message to all 
windows by setting the first parameter of SendMessage to -1, as shown: 

SendMessage (-1, WM_DDE_INITIATE,hwndClient,MAKELONG(aApp, aTopic)); 

If the application has already obtained the window handle of the desired 
server, it can send WM_DDE_INITIATE directly to the server window by 
passing the server's window handle as the first parameter of 
SendMessage. 

Allocate aApplication and aTopic by calling GlobalAddAtom. 

When SendMessage returns, delete the aApplication and aTopic atoms. 
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Receiving To complete the initiation of a conversation, respond with one or more 
WM_DDE_ACK messages, where each message is for a separate topic. 
When sending WM_DDE_ACK message, create new aApplication and 
aTopic atoms; do not reuse the atoms sent with the WM_DDE_INITIATE 
message. 



WM DDE POKE 



This message, posted by a client application, requests the receiving 
(server) application to accept an unsolicited data item value. 

The receiving application is expected to reply with a positive 
WM_DDE_ACK message if it accepts the data, or with a negative 
WM_DDE_ACK message if it does not. 



Parameter Description 



wParam Identifies the sending window. 

Waram Identifies the data and specifies how it is sent. 

Argument Description 

hData Low-order word of Waram. A handle that specifies the 

global memory object containing the data and other 
information. 

altem High-order word of Waram. An atom that identifies the 

data item offered to the server application. 

Comments The global memory object identified by hData consists of a DDEPOKE data 
structure that contains the following: 



Word 



Name 



Content 



3-n 



reserved 
fRelease 



reserved 
cfFormat 



Value[ ] 



Bits 15-14 are reserved. 

If bit 13 is 1, the receiving (server) application is 

expected to free the memory object after processing 

it. If bit 13 is zero, the receiving application should 

not free the object. See the following "Posting" and 

"Receiving" sections for exceptions. 

Bits 12-0 are reserved. 

This specifies the client's preferred type of data. It 

must be a standard or registered clipboard data 

format. 

This is the data. It is in the format specified by 

cfFormat. 
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Posting Post the WM_DDE_POKE message by calling the PostMessage function, 
not SendMessage. 

Allocate hData by calling the GlobalAlloc function with the 
GMEM_DDESHARE option. 

Allocate altem by calling the Global Add Atom function. 

If the receiving (server) application responds with a negative 
WM_DDE_ACK message, the sending (client) application must delete the 
hData object. 

If the sending (client) application sets the f Release flag to zero, the 
sending application must delete hData upon receiving either a positive or 
negative WM_DDE_ACK message. 

Receiving Post the WM_DDE_ACK message to respond positively or negatively. 
When posting WM_DDE_ACK, reuse the altem atom or delete it and 
create a new one. 

After processing the WM_DDE_POKE message, delete hData unless either 
of the following conditions is true: 

■ The f Release flag is zero. 

■ The f Release flag is 1, but the receiving (server) application responds 
with a negative WM_DDE_ACK message. 

WM_DDE_REQUEST 

This message, posted by a client application, requests the receiving 
(server) application to provide the value of a data item. 



Parameter Description 



wParam Identifies the sending window. 

IParam Specifies the requested data and the clipboard format number for the 
data 

Argument Description 

cfFormat Low-order word of IParam. A standard or registered 

clipboard format number. 
altem High-order word of IParam. An atom that specifies 

which data item is being requested from the server. 

Posting Post the WM_DDE_REQUEST message by calling the PostMessage 
function, not SendMessage. 
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Allocate altem by calling the GlobalAddAtom function. 

Receiving If the receiving (server) application can satisfy the request, it responds 
with a WM_DDE_DATA message containing the requested data. 
Otherwise, it responds with a negative WM_DDE_ACK message. 

When responding with either a WM_DDE_DATA or WM_DDE_ACK 
message, reuse the altem atom or delete it and create a new one. 

WM_DDE_TERMINATE 

This message, posted by either a client or server application, terminates a 
conversation. 

Parameter Description 

wParam Identifies the sending window. 

IParam Is reserved. 

Posting Post the WM_DDE_TERMINATE message by calling the PostMessage 
function, not SendMessage. 

While waiting for confirmation of the termination, the sending application 
should not acknowledge any other messages sent by the receiving 
application. If the sending application receives messages (other than 
WM_DDE_TERMINATE) from the receiving application, it should delete 
any atoms or shared memory objects accompanying the messages. 

Receiving Respond by posting a WM_DDE_TERMINATE message. 

WM_DDE_UNADVISE 

This message, sent by a client application, informs a server application 
that the specified item, or a particular clipboard format for the item, 
should no longer be updated. This terminates the warm or hot link for the 
specified item. 

Parameter Description 

wParam Identifies the sending window. 

IParam Specifies the data-request item to be canceled. 

Argument Description 

altem High-order word of IParam. An atom that specifies 

the data for which the update request is being 
retracted. When altem is NULL, all active 
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WM_DDE_ADVISE conversations associated with 
the client are to be terminated. 
cfFormat Low-order word of iParam. The clipboard format of 

the item that specifies the clipboard format for 
which the update request is being retracted. When 
cfFormat is NULL, all active WM_DDE_ADVISE 
conversations for the item are to be terminated. 

Posting Post the WM_DDE_UNADVISE message by calling the PostMessage 
function, not Send Message. 

Allocate altem by calling the GlobalAddAtom function. 

Receiving Post the WM_DDE_ACK message to respond positively or negatively. 
When posting WM_DDE_ACK, reuse the altem atom or delete it and 
create a new one. 
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Virtual-key codes 



The following table shows the symbolic constant names, hexadecimal 
values, and descriptive information for Microsoft Windows virtual-key 
codes. The codes are listed in numeric order. 



Name 


Value 


Description 


VK LBUTTON 


01H 


Left mouse button 


VK RBUTTON 


02H 


Right mouse button 


VK CANCEL 


03H 


Used for control-break processing 


VK_MBUTTON 


04H 


Middle mouse button 
(3-button mouse) 




05H-07H 


Undefined 


VK BACK 


08H 


BACKSPACE key 


VKJTAB 


09H 


TAB key 




OAH-OBH 


Undefined 


VK CLEAR 


OCH 


CLEAR key 


VK RETURN 


ODH 


RETURN key 


VK SHIFT 


10H 


SHIFT key 


VK CONTROL 


11H 


CONTROL key 


VK MENU 


12H 


MENU key 


VK PAUSE 


13H 


pause key 


VK_CAPITAL 


14H 


CAPITAL key 




15H-19H 


Reserved for Kanji systems 




1AH 


Undefined 


VK_ESCAPE 


1BH 


ESCAPE key 




1CH-1FH 


Reserved for Kanji systems 


VK SPACE 


20H 


SPACEBAR 


VK PRIOR 


21H 


PAGE UP key 


VK NEXT 


22H 


PAGE DOWN key 


VK END 


23H 


END key 


VK HOME 


24H 


HOME key 


VK LEFT 


25H 


LEFT ARROW key 
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VK UP 


VK RIGHT 


VK DOWN 


VK_SELECT 


VK EXECUTE 


VK_SNAPSHOT 


VK INSERT 


VK DELETE 


VK HELP 


VK 


VK 1 


VK 2 


VK 3 


VK 4 


VK 5 


VK 6 


VK 7 


VK 8 


VK_9 


VK A 


VK B 


VK C 


VK D 


VK E 


VK F 


VK G 


VK H 


VK I 


VKJ 


VK K 


VK L 


VK M 


VK N 


VK O 


VK P 


VK Q 


VK R 


VK S 


VK T 


VK U 


VK V 


VK W 


VK X 


VK Y 


VK_Z 


VK NUMPADO 


VK NUMPAD1 


VK NUMPAD2 



26H 


up arrow key 


27H 


RIGHT arrow key 


28H 


DOWN ARROW key 


29H 


SELECT key 


2AH 


OEM specific 


2BH 


EXECUTE key 


2CH 


PRINTSCREEN key for Windows 




version 3.0 and later 


2DH 


INSERT key 


2EH 


DELETE key 


2FH 


HELP key 


30H 


Okey 


31H 


l key 


32H 


2 key 


33H 


3 key 


34H 


4 key 


35H 


5 key 


36H 


6 key 


37H 


7 key 


38H 


8 key 


39H 


9 key 


3AH-40H 


Undefined 


41H 


A key 


42H 


Bkey 


43H 


Ckey 


44H 


Dkey 


45H 


Ekey 


46H 


Fkey 


47H 


Gkey 


48H 


Hkey 


49H 


I key 


4AH 


J key 


4BH 


Kkey 


4CH 


Lkey 


4DH 


Mkey 


4EH 


Nkey 


4FH 


Okey 


50H 


Pkey 


51H 


Qkey 


52H 


Rkey 


53H 


Skey 


54H 


Tkey 


55H 


Ukey 


56H 


Vkey 


57H 


wkey 


58H 


xkey 


59H 


Ykey 


5AH 


zkey 


5BH-5FH 


Undefined 


60H 


Numeric key pad key 


61H 


Numeric key pad 1 key 


62H 


Numeric key pad2 key 
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VK NUMPAD3 


63H 


Numeric key pad 3 key 


VK NUMPAD4 


64H 


Numeric key pad 4 key 


VK NUMPAD5 


65H 


Numeric key pad 5 key 


VK NUMPAD6 


66H 


Numeric key pad 6 key 


VK NUMPAD7 


67H 


Numeric key pad 7 key 


VK NUMPAD8 


68H 


Numeric key pad 8 key 


VK NUMPAD9 


69H 


Numeric key pad 9 key 


VK MULTIPLY 


6AH 


Multiply key 


VK ADD 


6BH 


Add key 


VK SEPARATER 


6CH 


Separater key 


VK SUBTRACT 


6DH 


Subtract key 


VK DECIMAL 


6EH 


Decimal key 


VK DIVIDE 


6FH 


Divide key 


VK Fl 


70H 


Fl key 


VK F2 


71H 


F2key 


VK F3 


72H 


F3key 


VK F4 


73H 


F4key 


VK F5 


74H 


F5key 


VK F6 


75H 


F6key 


VK F7 


76H 


F7key 


VK F8 


77H 


F8key 


VK F9 


78H 


F9key 


VK F10 


79H 


FlO key 


VK Fll 


7AH 


Fll key 


VK F12 


7BH 


F12 key 


VK F13 


7CH 


F13 key 


VK F14 


7DH 


F14 key 


VK F15 


7EH 


F15 key 


VK_F16 


7FH 


F16 key 




80H-87H 


OEM specific 




88H-8FH 


Unassigned 


VK_NUMLOCK 


90H 


NUM LOCK key 




91H 


OEM specific 




92H-B9H 


Unassigned 




BAH-COH 


OEM specific 




C1H-DAH 


Unassigned 




DBH-E4H 


OEM specific 




E5H 


Unassigned 




E6H 


OEM specific 




E7H-E8H 


Unassigned 




E9H-F5H 


OEM specific 




F6H-FEH 


Unassigned 
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RC diagnostic messages 



See Chapter 8, 

"Resource script 

statements," for 

information on the 

keywords and fields 

specified in this 

appendix. 



This appendix contains descriptions of diagnostic messages produced by 
the Resource Compiler (RC). Many of these messages appear when the 
Resource Compiler is not able to compile your resources. The descriptions 
in this appendix can help you determine the problem. 

A (V) symbol at the beginning of a message description indicates that the 
message is displayed only if RC is run with the -V (verbose) option. These 
messages are generally informational and do not necessarily indicate 
errors. 

The messages are listed in alphabetical order. 

Accelerator Type required (ASCII or VIRTKEY) 

The type field in the ACCELERATORS statement must contain either 
the ASCII or VIRTKEY value. 

BEGIN expected in Accelerator Table 

The BEGIN keyword must immediately follow the ACCELERATORS 

keyword. 

BEGIN expected in Dialog 

The BEGIN keyword must immediately follow the DIALOG keyword. 

BEGIN expected in menu 

The BEGIN keyword must immediately follow the MENU keyword. 

BEGIN expected in RCData 

The BEGIN keyword must immediately follow the RCDATA keyword. 
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BEGIN keyword expected in String or Error Table 

The BEGIN keyword must immediately follow the STRINGTABLE or 
ERRTABLE keyword. 

Cannot Reuse String Constants 

You are using the same value twice in a STRINGTABLE or ERRTABLE 

statpmpnt A/TaVp> ciirp> wr»ii aro nnt mivino- r\•^T(*r^ar^r^i■r\cr rlorimal anrl 

hexadecimal values. 

Control Character out of range [ A A - A Z] 

A control character in the ACCELERATORS statement is invalid. The 
character following the caret ( A ) must be between A and Z, inclusive. 

copy of temp-file-2 to exe-file failed 

The temporary file was not able to create the new .EXE file. Make sure 
that the TEMP environment variable is pointing to a drive that is not 
write-protected. 

Copying segment id (size bytes) 

(V) RC is copying the specified segment to the .EXE file. 

Could not find RCPP.EXE 

RCPP.ERR must be in the current directory or a directory in the PATH 
environment. 

Could not open in-file-name 

RC could not open the specified file. Make sure the file exists and that 
you typed the filename correctly. 

Couldn't open resource-name 

RC could not open the specified file. Make sure the file exists and that 
you typed the filename correctly. 

Couldn't write executable 

The .EXE file could not be copied to the temporary file. Make sure that 
the TEMP environment variable is pointing to a drive that is not write- 
protected and that the .EXE file from the linker is correct. You can 
check the .EXE file with the EXEHDR program. 
Creating resource-name 

(V) RC is creating a new .RES file. 

Empty menus not allowed 

An END keyword appears before any menu items are defined in the 
MENU statement. Empty menus are not permitted by the Resource 
Compiler. Make sure you do not have any open quotation marks within 
the MENU statement. 
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END expected in Dialog 

The END keyword must occur at the end of a DIALOG statement. Make 
sure there are no open quotes left from the preceding statement. 

END expected in menu 

The END keyword must come at the end of a MENU statement. Make 
sure you do not have any open quotation marks or a mismatched pair 
of BEGIN and END statements. 

Error: Bitmap file resource-file is not in 3.00 format. 

Use SDKPaint to convert version 2.x resource files to the 3.0 format. 

Error Creating resource-name 

Could not create specified .RES file. Make sure it is not being created on 
a read-only drive. Use the -V option to find out whether the file is 
being created. 

Error: I/O error reading file. 

Read failed. Since this is a generic routine, no specific filename is 
supplied. 

Error: I/O error seeking in file 

Seeking in file failed. 

Error: I/O error writing file. 

Write failed. Since this is a generic routine, no specific filename is 
supplied. 

Error: Old DIB in resource-name. Pass it through SDKPAINT. 

The resource file specified is not compatible with Windows 3.0. Make 
sure you have read and saved this file using the latest version of 
SDKPaint. 

Error: Out of memory. Try not using resources with string identifiers. 

There is not enough memory to allocate for a table of string names. You 
can view these names are when you use the -V option. Try to replace 
the string names with numbers. For example, you can change 

MYICON ICON myicon.ico 

to 

1 ICON myicon.ico 

or provide the following statement in your header file: 

tdefine MYICON 1 
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Error: Resource file resouce-name is not in 3.00 format. 

Make sure your icons and cursors have been read and saved using the 
latest version of SDKPaint. 

Errors in .EXE file 

LINK failed. See the CodeView and Utilities manual in the Microsoft C 5.1 
Optimizing Compiler documentation set for more information. 

.EXE file too large; relink with higher /ALIGN value 

The EXE file is too large. Relink the .EXE file with a larger /ALIGN 
value. If the .EXE file is larger than 800K, you should use the /ALIGN:32 
value on your LINK line. 

.EXE not created by LINK 

You must create the .EXE file with a version of LINK that is from C 
version 5.1 or later. 

Expected Comma in Accelerator Table 

RC requires a comma between the event and idvalue fields in the 
ACCELERATORS statement. 

Expected control class name 

The class field of a CONTROL statement in the DIALOG statement must 
be one of the following types: BUTTON, COMBOBOX, EDIT, LISTBOX, 
SCROLLBAR, STATIC, or user-defined. Make sure the class is spelled 
correctly. 

Expected font face name 

The typeface field of the FONT option in the DIALOG statement must be 
an ASCII character string enclosed in double quotation marks. This 
field specifies the name of a font. 

Expected ID value for Menuitem 

The MENU statement must contain a menuID field, which specifies the 
name or number that identifies the menu resource. 

Expected Menu String 

Each MENUITEM and POPUP statement must contain a text field, which 
is a string enclosed in double quotation marks that specifies the name 
of the menu item or pop-up menu. A MENUITEM SEPARATOR 
statement requires no quoted string. 

Expected numeric command value 

RC was expecting a numeric idvalue field in the ACCELERATORS 
statement. Make sure you have used a #define constant to specify the 
value and that the constant is spelled correctly. 
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Expected numeric constant in string table 

A numeric constant, defined in a #define statement, must immediately 
follow the BEGIN keyword in a STRINGTABLE or ERRTABLE 

statement. 

Expected numeric point size 

The pointsize field of the FONT option in the DIALOG statement must be 
an integer point size value. 

Expected Numerical Dialog constant 

A DIALOG statement requires integer values for the x, y, width, and 
height fields. Make sure these values are included after the DIALOG 
keyword and that they are not negative. 

Expected String in STRINGTABLE/ERRTABLE 

A string is expected after each stringid value in a STRINGTABLE or 
ERRTABLE statement. 

Expected String or Constant Accelerator command 

RC was not able to determine what kind of key is being set up for the 
accelerator. The event field in the ACCELERATORS statement might be 
invalid. 

Expecting number for ID 

Expecting a number for the id field of a control statement in the 
DIALOG statement. Make sure you have a number or #define statement 
for the control ID. 

Expecting quoted string in dialog class 

The class field of the CLASS option in the DIALOG statement must be 
an integer or a string, enclosed in double quotation marks. 

Expecting quoted string in dialog title 

The captiontext field of the CAPTION option in the DIALOG statement must 
be an ASCII character string enclosed in double quotation marks. 

File not found: filename 

The file specified in the RC command line was not found. Check to see 
whether the file has been moved to another directory and whether the 
filename or pathname is typed correctly. 

Font names must be ordinals 

The pointsize field in the FONT statement must be an integer, not a 
string. 

Gangload area is [size] bytes at offset Ox[address] 

(V) This is the size (in bytes) of all the segments that have one of the 
following attributes: 
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■ PRELOAD 

■ DISCARDABLE 

■ Code segments that contain the entry point, WinMain 

■ Data segments (which should not be discardable) 

The segments are placed in a continguous area in the .EXE file for fast 
loading. The offset value is from the the beginning of the file. To 
disable gangloading, use the -k option. 

Insufficient memory to spawn RCPP.EXE 

There wasn't enough memory to run the preprocessor (RCPP). You can 
try not running any memory-resident software that might be taking up 
too much memory. Use the CHKDSK program to verify the amount of 
memory you have. 

Invalid Accelerator 

An event field in the ACCELERATORS statement was not recognized or 
was more than two characters in length. 

Invalid Accelerator Type (ASCII or VIRTKEY) 

The type field in the ACCELERATORS statement must contain either 
the ASCII or VIRTKEY value. 

Invalid control character 

A control character in the ACCELERATORS statement is invalid. A 
valid control character consists of one letter (only) following a caret ( A ). 

Invalid Control type 

Each control statement in a DIALOG statement must be one of the 
following: CHECKBOX, COMBOBOX, CONTROL, CTEXT, 
DEFPUSHBUTTON, EDITTEXT, GROUPBOX, ICON, LISTBOX, LTEXT, 
PUSHBUTTON, RADIOBUTTON, RTEXT, SCROLLBAR. 

Make sure these control statements are spelled correctly. 

Invalid .EXE file 

The .EXE file is invalid. Make sure that the linker created it correctly 
and that the file exists. You can check the .EXE file with the EXEHDR 
program. 

Invalid switch, option 

You used an option that was not valid. Use RC -? for a list of the 
command-line options. 

Invalid type 

The resource type was not among the types defined in the windows. h 
file. 
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Invalid usage. Use re -? for Help 

Make sure you have at least one filename to work with. Use RC -? for 
a list of the command-line options. 

No executable filename specified. 

The -FE option was used, but no .EXE filename specified. 

No resource binary filename specified. 

The -FO option was used, but no .RES filename specified. 

Not a Microsoft Windows format .EXE file 

Make sure that the linker created the .EXE file correctly and that the file 
exists. You can check the .EXE file with the EXEHDR program. 

Out of far heap memory 

There wasn't enough memory. Try not running any memory-resident 
software that might be taking up too much space. Use the CHKDSK 
program to find out how much memory you have. 

Out of memory, needed n bytes 

RC was not able to allocate the specified amount of memory. 

RC: Invalid swap area size: -S string 

Invalid swap area size. Check your syntax for the -S option on the RC 
command line. The following are acceptable command lines: 

RC S123 

RC S123K ;where K is kilobytes 

RC S123p /where p is paragraphs 

RC: Invalid switch: option 

You used an option that was not valid. Use RC -? for a list of the 
command-line options. 

RC: RCPP preprocessor-command-string 

(V) RC is passing the specified string to the preprocessor. 

RC: RCPP.ERR not found 

RCPP.ERR must be in the current directory or a directory in the PATH 
environment. 

RC terminated by user 

A CONTROL+C key combination was pressed, terminating RC. 

RC terminating after preprocessor errors 

See the Microsoft C 5.1 Optimizing Compiler documentation for 
information about preprocessor errors. 

RCPP.EXE command line greater than 128 bytes 

The command line was too long. 
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RCPP.EXE is not a valid executable 

RCPP.EXE is not valid. The file might have been altered. Try copying 
the file from the SDK disks. 

Reading resource-name 

(V) RC is reading the .RES file. 

Resources will be aligned on number byte boundaries 

(V) The alignment is determined by the ALIGN: number option on the 
LINK line. 

Sorting preload segments and resources into gangload section 

(V) RC is sorting the preloaded segments so that they can be loaded 
quickly. 

Text string or ordinal expected in Control 

The text field of a CONTROL statement in the DIALOG statement must 
be either a text string or an ordinal reference to the type of control is 
expected. If using an ordinal, make sure that you have a #define 
statement for the control. 

The EXETYPE of this program is not Windows 

The EXETYPE WINDOWS statement did not appear in the .DEF file. 
Since the linker might make optimizations for OS/2 (the default 
EXETYPE) that are not appropriate for Windows, the EXETYPE 
WINDOWS statement must be specified. 

Unable to create destination 

RC was not able to create the destination file. Make sure there is 
enough disk space. 

Unable to open exe-file 

RC could not open this .EXE file. Make sure that the linker created it 
correctly and that the file exists. 

Unbalanced Parentheses 

Make sure you have closed every open parenthesis in the DIALOG 
statement. 

Unexpected value in RCData 

The raw-data values in the RCDATA statement must be integers or 
strings, each separated by a comma. Make sure you did not leave out a 
comma or leave out a quotation mark around a string. 

Unknown DIB header format 

The bitmap header is not a BITMAPCOREHEADER or 
BITMAPINFOHEADER structure. 
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Unknown error spawning RCPP.EXE 

For an unknown reason, RCPP was not started. Try copying the file 
from the SDK disks, and use the CHKDSK program to verify the 
amount of available memory. 

Unknown Menu SubType 

The item-definition field of the MENU statement can contain only 
MENUITEM and POPUP statements. 

Warning: ASCII character not equivalent to virtual key code 

There is an invalid virtual-key code in the ACCELERATORS statement. 
The ASCII value for some characters (such as *, A , &,) is not equivalent 
to the virtual-key code for the corresponding key. (In the case of the 
asterisk (*), the virtual-key code is equivalent to the ASCII value for 8, 
the numeric character on the same key. Therefore the statement 

VIRTKEY '* ' 

is invalid.) See Appendix A, "Virtual-key codes," and Appendix D, 
"Character tables," for these values. 

Warning: Discardable segment id (hex-size bytes) is excessively large. 

The segment is greater than 27FFh in size. RC displays this warning 
because very large segments can adversely affect memory usage. Check 
your map file listing for the exact size of your segments. 

Warning: SHIFT or CONTROL used without VIRTKEY 

The ALT, SHIFT, and CONTROL options apply only to virtual keys in 
the ACCELERATORS statement. Make sure you have used the 
VIRTKEY option with one of these other options. 

Writing resource resource-name or ordinal-id resource type {resource 
size) 

(V) RC is writing the resource name or ordinal ID, followed by a period 
and the resource type and size (in bytes). 

Warning: string segment number set to PRELOAD 

RC displays this warning when it copies a segment that must be 
preloaded but that is not marked PRELOAD in the linker .DEF file. 

All nondiscardable segments should be preloaded, including automatic 
data segments, fixed segments and the entry point of the code 
(WinMain). The attributes of your code segments are set by the .DEF 
file. Check your map file listing for more information. 
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N 



D 



X 



[[ ]] (double brackets) 

as document convention 3 
. . . (ellipses) 

as document convention 3 
{ } (curly braces) 

as document convention 3 
( ) (parentheses) 

as document convention 3 
( A ) caret 68 
( A ) caret[#caret] 67 

& (ampersand) 80, 81, 82, 83, 84, 86, 87, 88 
I (vertical bar) 

as document convention 3 
\bcl69\ec \bcl70\ec (quotation marks) 

as document convention [(quotation marks), 

as document convention] 3 
\bcB\ecBold text\bcD\ec 

as document convention 2 
\bcF105M\ecMonospaced type\bcF255D\ec 

as document convention 3 
\bcMI\ eel talk text\bcD\ec 

as document convention 3 
\bcS\ecBACKSPACE\bcD\ec key 95 
\bcS\ecCONTROL\bcD\ec key 68 
\bcS\ecSHIFT\bcD\ec key 68 
\bcS\ecTAB\bcD\ec key 77 
#define directive 

[define directive] resource compiler 103 

resource compiler 103 
#elif directive 

[elif directive] resource compiler 106 
#else directive 

[else directive]resource compiler 106 
#endif directive 

[endif directive] resource compiler 107 

resource compiler 107 
#if directive 

[if directive]resource compiler 105 



resource compiler 105, 106 
#ifdef directive 

[if def directive] resource compiler 104 

resource compiler 104 
#ifndef directive 

[ifndef directive]resource compiler 105 

resource compiler 105 
#include directive 

[include directive] resource compiler 103 

resource compiler 103 
#undef directive 

[undef directive] resource compiler 104 

resource compiler 104 

A 

ABORTDOC printer escape 753 
ACCELERATORS resource statement 67 
Addition (+) operator 80, 81, 82, 83, 85, 86, 87, 
88, 89, 90, 91, 92 

B 

BANDINFO printer escape 154 
BEGIN_PATH printer escape 156 
BITMAP data structure 10 
BITMAP resource-compiler key word 62 
BITMAPCOREHEADER data structure 11,13 
BITMAPCOREINFO data structure 12 
BITMAPFILEHEADER data structure 14 
BITMAPINFO data structure 14,17 
BITMAPINFOHEADER data structure 15, 16 
BOOL data type 7 
Border 

window 76 
Braces 

curly ({ }) 
as document convention 3 
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Brackets 

double ([[]]) 
as document convention 3 
BS_3STATE control style 96 
BS_AUT03STATE control style 96 
BS_AUTOCHECKBOX control style 96 
BS_AUTORADIOBUTTON control style 96 
BS_CHECKBOX control style 96 
BS_DEFPUSHBUTTON control style 96 
BS_GROUPBOX control style 96 
BS_HATCHED brush style 38, 39 
BSJHOLLOW brush style 39 
BS_LEFTTEXT control style 96 
BS_OWNERDRAW control style 96 
BS_PATTERN brush style 39 
BS_PUSHBUTTON control style 96 
BS_RADIOBUTTON control style 96 
BS_SOLID brush style 39 
Button 

owner-draw 36, 46 
BUTTON control class 83, 85, 86, 95 
BYTE data type 7 



Capital letters 

small 
as document convention 3 
CAPTION resource statement 77 
Caret ( A ) 68, 95 
Caret (\bc94\ec) 67 
Carriage-return character 98 
CB_ADDSTRING message 37, 47 
CBJNSERTSTRING message 37, 47 
CBS_AUTOHSCROLL control style 97 
CBS_DROPDOWN control style 97 
CBS_DROPDOWNLIST control style 97 
CBS_HASSTRINGS control style 97 
CBS_OEMCONVERT control style 97 
CBS_OWNERDRAWFIXED control style 97 
CBS_OWNERDRAWVARIABLE control style 

97 
CBS_SIMPLE control style 97 
CBS_SORT control style 97 
char data type 7 

CHECKBOX resource statement 83, 84 
CLASS resource statement 78 



CLIENTCREATESTRUCT data structure 20 
CLIP_TO_PATH printer escape 157 
Clipping 

child window 76 
CODE module-definition statement 734 
Code segment attributes 

defining 134, 140 
CODE statement 133 
COLORREF data type 20 
Combo box 

owner-draw 28 

sorting owner-draw 22 
COMBOBOX control class 91, 95 
COMBOBOX resource statement 91, 92 
Communication devices 23, 25 
COMPAREITEMSTRUCT data structure 22 
COMSTAT data structure 23 
CONTROL resource statement 94 
Control window 

user-defined 94 
CREATESTRUCT data structure 24 
Creating windows 75 

CS_BYTEALIGNCLIENT window class style 58 
CS_BYTEALIGNWINDOW window class style 

58 
CS_CLASSDC window class style 58 
CS_DBLCLKS window class style 58 
CS_HREDRAW window class style 59 
CS_NOCLOSE window class style 59 
CS_OWNDC window class style 59 
CS_PARENTDC window class style 59 
CS_SAVEBITS window class style 59 
CS_VREDRAW window class style 59 
CTEXT resource statement 82 
Curly braces ({ }) 

as document convention 3 
CURSOR resource-compiler key word 62 
CW USEDEFAULT default window width 45 



DATA module-definition statement 135 
Data segment attributes 

defining 135, 140 
DATA statement 133 
Data types 

naming conventions 7, 9 
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DCB data structure 25 
Default pushbutton control 87 
DefDlgProc function 78 
DEFPUSHBUTTON resource statement 87, 88 
DESCRIPTION module-definition statement 

135 
DESCRIPTION statement 133 
DEVICEDATA printer escape 158 
Devices 

communication 23, 25 
DEVMODE data structure 29 
Dialog box units 80, 81, 82, 83, 84, 85, 87, 88, 

89, 90, 91 
Dialog option statements 75 
DIALOG resource statement 73 
DIALOG template 73 
DialogBox function 74 
Disabled window 74 
DISCARDABLE resource-compiler key word 

62, 64, 65, 66, 69, 74 
DLGITEMTEMPLATE data structure 34 
DLGTEMPLATE data structure 32 
Double brackets ([[ ]]) 

as document convention 3 
Double quotation marks (\bcl69\ec\bcl70\ec) 

66, 67, 70, 78 
Double quotation marks (\bcl70\ec\bcl69\ec) 

70 
DRAFT_QUALITY font quality 41 
DRAFTMODE printer escape 158 
DRAWPATTERNRECT printer escape 158 
Driver 

printer initialization 29 
DS_ABSALIGN dialog-box style 33, 74 
DS_LOCALEDIT dialog-box style 33, 76 
DS_MODALFRAME dialog-box style 33, 76 
DS_NOIDLEMSG dialog-box style 33, 76 
DS_SETFONT dialog-box style 33 
DS_SYSMODAL dialog-box style 33, 76 
DWORD data type 8 



Edit control 90, 98 

EDIT control class 95 

Editing keys 90 

EDITTEXT resource statement 89, 90 



EM_SETPASSWORDCHAR message 98 
ENABLEDUPLEX printer escape 160 
ENABLEPAIRKERNING printer escape 160 
ENABLERELATIVEWIDTHS printer escape 

161 
END_PATH printer escape 162 
ENDDOC printer escape 162 
ENUMPAPERBINS printer escape 164 
ENUMPAPERMETRICS printer escape 165 
EPSPRINTING printer escape 166 
ES_AUTOHSCROLL control style 99 
ES_AUTOVSCROLL control style 98 
ES_CENTER control style 97 
ES_LEFT control style 97 
ES_LOWERCASE control style 98 
ES_MULTILINE control style 98 
ES_NOHIDESEL control style 99 
ESJDEMCONVERT control style 99 
ES_PASSWORD control style 98 
ES_RIGHT control style 97 
ESJJPPERCASE control style 98 
EVENPARITY parity type 26 
EXETYPE module-definition statement 136 
EXPORTS module-definition statement 136 
EXPORTS statement 133 
EXT_DEVICE_CAPS printer escape 166 
EXTTEXTOUT printer escape 168 



FAR data type 8 

FARPROC data type 8 

FF_DECORATIVE font family 42 

FF_DONTCARE font family 42 

FF_MODERN font family 42 

FF_ROMAN font family 42 

FF_SCRIPT font family 42 

FF_SWISS font family 43 

FIXED resource-compiler key word 62, 63, 65, 

66, 69, 73 
FLUSHOUTPUT printer escape 169 
FONT resource-compiler key word 62 
FONT resource statement 79 
FONTINFO data structure 34 



GETCOLORTABLE printer escape 169 
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GetDialogBaseUnits function 35, 74, 80, 81, 82, 
83, 84, 85, 86, 88, 89, 90, 91, 92, 93, 94, 100 
GETEXTENDEDTEXTMETRICS printer escape 

170 
GETEXTENTTABLE printer escape 173 
GETFACENAME printer escape 174 
GETPAIRKERNTABLE printer escape 174 
GETPHYSPAGESIZE printer escape 176 
GETPRINTINGOFFSET printer escape 176 
GETSCALINGFACTOR printer escape 176 
GETSETPAPERBINS printer escape 177 
GETSETPAPERMETRICS printer escape 7 78 
GETSETPAPERORIENT printer escape 179 
GETSETPAPERORIENTATION printer escape 

180 
GETSETSCREENPARAMS printer escape 180 
GetSubMenu function 20 
GETTECHNOLOGY printer escape 181 
GETTRACKKERNTABLE printer escape 181 
GETVECTORBRUSHSIZE printer escape 182 
GETVECTORPENSIZE printer escape 183 
GLOBALHANDLE data type 8 
GRAYED menu-item option 48 
GROUPBOX resource statement 86, 87 

H 

HANDLE data type 8 
Handle table 38 

HANDLETABLE data structure 38 
HBITMAP data type 8 
HBRUSH data type 8 
HCURSOR data type 8 
HDC data type 8 
Heap 

local 137 
HEAPSIZE module-definition statement 137 
HEAPSIZE statement 133 
HELP option 

MENUITEM resource statement 71 
HFONT data type 8 
HICON data type 8 
HMENU data type 8 
HPALETTE data type 8 
HPEN data type 8 
HRGN data type 8 
HS_BDIAGONAL brush hatch style 39 



HS_CROSS brush hatch style 39 
HS_DIAGCROSS brush hatch style 39 
HS_FDIAGONAL brush hatch style 39 
HS_HORIZONTAL brush hatch style 39 
HSJ/ERTICAL brush hatch style 39 
HSTR data type 8 
hWindowMenu 20 

I 

Icon resource 62 

ICON resource-compiler key word 62 

ICON resource statement 92 

IMPORTS module-definition statement 138 

IMPORTS statement 133, 138 

INCLUDE environmental variable 103 

IncUpdate 52 

InsertMenu function 37 

int data type 8 



LB_ADDSTRING message 28, 37, 47 
LBJNSERTSTRING message 28, 37, 47 
LB_SETCOLUMNWIDTH message 99 
LBS_EXTENDEDSEL control style 99 
LBS_HASSTRINGS control style 99 
LBS_MULTICOLUMN control style 99 
LBS_MULTIPLESEL control style 99 
LBS_NOINTEGRALHEIGHT control style 99 
LBS_NOREDRAW control style 100 
LBS_NOTIFY control style 99 
LBSJDWNERDRAWFIXED control style 100 
LBS_OWNERDRAWVARIABLE control style 

100 
LBS_SORT control style 99 
LBS_STANDARD control style 99 
LBS_WANTKEYBOARDINPUT control style 

100 
Library module 139 

LIBRARY module-definition statement 739 
LIBRARY statement 133, 139 
LISTBOX control class 85, 95 
LISTBOX resource statement 85, 86 
LOADONCALL resource-compiler key word 

62, 63, 65, 66, 69, 73 
LoadString function 66 
Local heap 137 
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Local stack 141 
LOCALHANDLE data type 8 
LOGBRUSH data structure 38 
LOGFONT data structure 40 
LOGPALETTE data structure 43, 52 
LOGPEN data structure 44 
LONG data type 8 
long data type 8 
LPBITMAP data type 8 
LPBITMAPCOREHEADER data type 8 
LPBITMAPCOREINFO data type 8 
LPBITMAPFILEHEADER data type 8 
LPBITMAPINFO data type 8 
LPBITMAPINFOHEADER data type 8 
LPCOMPAREITEMSTRUCT data type 8 
LPCREATESTRUCT data type 8 
LPDELETEITEMSTRUCT data type 9 
LPDRAWITEMSTRUCT data type 9 
LPHANDLETABLE data type 9 
LPINT data type 9 
LPLOGBRUSH data type 9 
LPLOGFONT data type 9 
LPLOGP ALETTE data type 9 
LPLOGPEN data type 9 
LPMEASUREITEMSTRUCT data type 9 
LPMETAFILEPICT data type 9 
LPMSG data type 9 
LPOFSTRUCT data type 9 
LPPAINTSTRUCT data type 9 
LPPALETTEENTRY data type 9 
LPPOINT data type 9 
LPRECT data type 9 
LPSTR data type 9 
LPTEXTMETRIC data type 9 
LPVOID data type 9 
LPWNDCLASS data type 9 
LTEXT resource statement 80 

M 

MakeProcInstance function 8 
MARKPARITY parity type 26 
Maximize box 76 

MDICREATESTRUCT data structure 45 
MEASUREITEMSTRUCT data structure 46, 47 
MENU resource statement 68, 69, 70, 71, 73, 78 
MENUITEM SEPARATOR statement 73 



MENUITEM statement 70 
MENUITEMTEMPLATE data structure 47 
Metafile picture format 49 
METAFILEPICT data structure 49 
MF_CHECKED menu option 48 
MF_END menu option 48 
MF_HELP menu-item option 48 
MF_MENUBARBREAK menu-item option 48 
MF_MENUBREAK menu-item option 48 
MF_OWNERDRAW menu-item option 48 
MF_POPUP menu-item option 48 
MFCOMMENT printer escape 183 
MIDCREATESTRUCT menu flag 46 
Minimize box 76 

Mnemonic 70, 80, 81, 82, 83, 84, 86, 87, 88 
MOVEABLE resource-compiler key word 62, 

64, 65, 66, 69, 73 
MSG data structure 50 
MULTIKEYHELP data structure 50 
Multiple-line edit control 98 

N 

n& (ampersand) [#ampersand] 

use in MENUITEM statement 70 
n\a See Escape character 
n.DEF file See Module-definition file 
n#include directive [include directive] 

when required with STYLE statement 75 
n\t See Escape character 
^Accelerator See ACCELERATORS resource 

statement 
NAME module-definition statement 139 
NAME statement 133 
nAmpersand (&) 

adding a mnemonic with 70, 80, 81, 82, 83, 
84, 86, 87, 88 
nASCII character 

use with ACCELERATORS statement 67 
nBitmap 

device-independent 
BITMAPCOREHEADER data structure 12 
BITMAPCOREINFO data structure 13 
BITMAPINFO data structure 15 
BITMAPINFOHEADER data structure 17 
color 55 
described 12, 13, 15, 16 
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file format 109 

file format 14 

mouse cursor shape 62 

resource 62 
nBITMAPCOREINFO See also RGBTRIPLE 
nBITMAPINFO See also RGBQUAD 
nBrush 

creating 38 
nBUTTON control class 

control styles 83, 87, 88, 89, 96 
nCharacter 

escape® \ a 70 

escape@\t 70 
nCHECKBOX resource statement 

DIALOG resource statement 79 
nCHECKED option 

MENUITEM resource statement 71 

POPUP resource statement 72 
nChild window 

clipping 76 
nClient area 

painting 52 
nClipboard 

file format 113 
nColor 

data types 20 

explicit RGB 20 

logical-palette index 20 

palette-relative RGB 20 

specifying 20 
nColor palette See also Logical palette 
nCOMBOBOX control class 

control styles 91,97 
nCOMBOBOX resource statement 

DIALOG resource statement 79 
nControl 

owner-draw 
drawing 36 
item deleted from 28 

size-box 95 
nControl class 

BUTTON@control styles 96 

BUTTON@described 95 

COMBOBOX@described 95 

control styles@described 96 

described 94 

EDIT 95 



control styles 97 

LISTBOX 95 

LISTBOX@control styles 99 

SCROLLBAR 95 

SCROLLBAR@control styles 100 

STATIC 95 
nControl edit See edit control 
nCONTROL option 

ACCELERATORS resource statement 68 
nCONTROL resource statement 

DIALOG resource statement 79 
nControl styles 

BUTTON class 96 

COMBOBOX class 97 

described 96 

EDIT class 97 

LISTBOX class 99 

SCROLLBAR class 100 
nControl text 

centered 82 

left-justified 80 

right-justified 81 
nCreateWindow function 

creating a window with dialog-box attributes 

75 
nCursor 

file format 11 1 

resource 62 
nDDE 

messages 206 

protocol 205 
nDEFPUSHBUTTON resource statement 

DIALOG resource statement 79 
nDELETEITEMSTRUCT data structure 

described 28 
nDevice-independent bitmap See Bitmap, 

device-independent 
nDEVICEDATA printer escape See 

PASSTHROUGH printer escape 
nDialog box 

creating 32, 73 

items 34 

template 73 

text font 34 

window style 75 
nDIALOG resource statement 

control class@control styles 96 
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2RTEXT 79, 81 
5RTEXT statement 



dialog control statements@CHECKBOX 79, 
83 

dialog control statements@COMBOBOX 79, 
91 

dialog control statements@CONTROL 79, 94 
dialog control statements@Control classes 94 
dialog control statements@CTEXT 79, 82 
dialog control statements@CTEXT statement 
79 

dialog control 

statements@DEFPUSHBUTTON 79, 87 
dialog control statements@EDITTEXT 79, 89 
dialog control statements@GROUPBOX 79, 
86 

dialog control statements@ICON 79, 92 
dialog control statements@LISTBOX 79, 85 
dialog control statements@LTEXT 79, 80 
dialog control statements@PUSHBUTTON 
79,84 

dialog control statements@RADIOBUTTON 
79,88 

dialog control statements!? 
dialog control statements^ 
79 

dialog control statements@SCROLLBAR 93 
dialog option statement@CAPTION 75, 77 
dialog option statement@CLASS 75, 78 
dialog option statement@FONT 75, 79 
dialog option statement@MENU 75, 78 
dialog option statement@STYLE 75 
dialog option statement@STYLE 74 
nDIB_PAL_COLORS 

device-independent bitmap color table 
option 13,16, 39, 121 
nDIB_RGB_COLORS 

device-independent bitmap color table 
option 39, 121 
nDirective 

resource compiler 

#define 703 

#elif 106 

#else 106 

#endif 107 

#if 105 

#ifdef 104 

#ifndef 105 

#include 103 



#undef 104 
described 103 
nDLGTEMPLATE 

DLGITEMTEMPLATE data structure 34 

FONTINFO data structure 34 
nDocument conventions 

\bcB\ecbold text\bcD\ec 2 

\bcF105M\ecmonospaced type\bcF255D\ec 

3 

\bcMI\ecitalic text\bcD\ec 3 

curly braces ({ }) 3 

double brackets ([[ ]]) 3 

horizontal ellipses (...) 3 

parentheses ( ) 3 

quotation marks (\bcl69\ec \bcl70\ 

ec) [quotation marks ( )] 3 

small capital letters 3 

vertical bar ( I ) 3 

vertical ellipses 3 
nDRAWITEMSTRUCT data structure 

described 36 
nDrop-down menu See Pop-up menu 
nDynamic Data Exchange See DDE 
NEAR data type 9 
nEDIT control class 

control styles 90, 97 
nEDITTEXT resource statement 

style option 90 
nEDITTEXT statement 

DIALOG resource statement 79 
nEllipses 

horizontal 
as document convention 3 

vertical 
as document convention 3 
nEscape character 

\a70 

\t70 
nEscapes 

printer 153 
NEWFRAME printer escape 184 
nExporting 

function 139 
NEXTBAND printer escape 184 
nFile 

bitmap 

device-independent@format 109 
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clipboard@format 113 

cursor@format 111 

icon@format 110 

initialization@WINDOWS.H 75 

metafile@format 113 
nFile format 

module-definition file 133 
nFont 

resource 62 
nGRAYED option 

MENUITEM resource statement 71 

POPUP resource statement 71 
nGroup box 

BUTTON class 86 
nGROUPBOX resource statement 

DIALOG resource statement 79 
nHEAPSIZE statement 

syntax 137 
nlcon 

file format 110 
nICON resource statement 

DIALOG resource statement 79 
nINACTIVE option 

MENUITEM resource statement 71 

POPUP resource statement 71 
nKey 

\bcS\ecBACKSPACE\bcD\ec 95 

\bcS\ecCONTROL\bcD\ec 68 

\bcS\ecSHIFT\bcD\ec 68 

\bcS\ecTAB\bcD\ec 77 

editing 90 
nKey word 

resource-compiler 
BITMAP 62 
CURSOR 62 

DISCARDABLE 62, 64, 65, 66, 69, 74 
FIXED 62, 63, 65, 66, 69, 73 
FONT 62 
ICON 62 

LOADONCALL 62, 63, 65, 66, 69, 73 
MOVEABLE 62, 64, 65, 66, 69, 73 
PRELOAD 62, 63, 65, 66, 69, 73 
nList box 

owner-draw 28 

owner-draw@measuring 46 

owner-draw@sorting 22 



nLISTBOX control class 

control styles 86, 99 
nLISTBOX resource statement 

DIALOG resource statement 79 
nLogical palette See also LOGP ALETTE data 

structure 

creating 43 
nLTEXT resource statement 

DIALOG resource statement 79 
nMDI See Multiple document interface (MDI) 
nMenu 

loading 47 

owner-draw@drawing 36 

owner-draw@measuring 46 

resource 68 
nMENUBARBREAK option 

MENUITEM statement 71 

POPUP statement 72 
nMENUBREAK option 

MENUITEM statement 71 

POPUP statement 71 
nMetafile 

file format 1 13 
nModule-definition file 

CODE statement 134 

DATA statement 135 

DESCRIPTION statement 135 

EXETYPE statement 136 

EXPORTS statement 136 

HEAPSIZE statement 137 

IMPORTS statement 138 

LIBRARY statement 139 

module statement@description 133 

NAME statement 139 

SEGMENTS statement 140 

STACKSIZE statement 141 

STUB statement 141 
nModule statement 

in module definition file@description 133 
nMultiple Document Interface (MDI) 

child window@creating 45 
nMultiple document interface (MDI) 

child window 20 
nMultiple-line resource statement 

ACCELERATORS 67 

DIALOG 73 

MENU 68 
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RCDATA 64 

STRINGTABLE 65 
nNaming 

executable module 139 

imported functions 138 

library module 139 
nNaming conventions 

data types 9 
nNOINVERT option 

ACCELERATORS resource statement 68 
NOPARITY parity type 26 
nOption 

menu-item 
CHECKED 71, 72 
GRAYED 71 
HELP 71 
INACTIVE 71 
MENUBARBREAK 72 

MENUBARBREAK 71 

MENUBREAK 71 

SHIFT 68 
nOwner-draw button See Button owner-draw 
nOwner-draw control See Control owner-draw 
nOwner-draw menu See Menu, owner-draw 
nPalette See logical Logical palette 
nPen 

creating 44 
nPop-up menu 

described 71 

nested 72 
NPSTR data type 9 
nPUSHBUTTON resource statement 

DIALOG resource statement 79 
nRADIOBUTTON resource statement 

DIALOG resource statement 79 
nRaw-data resource See RCDATA resource 

statement 
nResource 

bitmap 62 

cursor 62 

font 62 

icon 62 

loading 62, 63, 65, 66, 73 

raw data 64 

string 66 

user-defined 63 



nResource directive 

#define[define] 103 

#elif[elif] 106 

#else[else] 106 

#endif[endif] 107 

#if[if] 105 

#ifdef[ifdef] 104 

#ifndef[ifndef] 105 

#include[include] 103 

#undef[undef] 104 

described 103 
nResource statement 

ACCELERATORS@CONTROL option 68 

ACCELERATORS@NOINVERT option 68 

ACCELERATORS@SHIFT option 68 

DIALOG 73 

DIALOG@CAPTION statement 77 

DIALOG@CHECKBOX statement 83 

DIALOG@CLASS statement 78 

DIALOG@COMBOBOX statement 91 

DIALOG@CONTROL statement 94 

DIALOG@CTEXT statement 82 

DIALOG@DEFPUSHBUTTON statement 87 

DIALOG@dialog control statements 79 

DIALOG@dialog option statements 75 

DIALOG@EDITTEXT statement 89 

DIALOG@FONT statement 79 

DIALOG@GROUPBOX statement 86 

DIALOG@ICON statement 92 

DIALOG@LISTBOX statement 85 

DIALOG@LTEXT statement 80 

DIALOG@MENU statement 78 

DIALOG@options 73 

DIALOG@PUSHBUTTON statement 84 

DIALOG@RADIOBUTTON statement 88 

DIALOG@RTEXT statement 81 

DIALOG@SCROLLBAR statement 93 

DIALOG@STYLE statement 75 

MENU 68, 69, 70, 71, 73 

RCDATA 64, 65 

resource 62 

single-line 61, 62 

STRINGTABLE 65, 66 

user-defined 63, 64 
nRGB See also Color 

explicit 20 

palette-relative 20 
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nScroll bar 
horizontal 76 
vertical 77 
nSCROLLBAR control class 

control styles 100 
nSELECTPAPERSOURCE printer escape See 

GETSETPAPERBIN T S printer escape 
nSETENDCAP printer escape See 

SETLINECAP printer escape 
nStatement See specific statement 

module-definition file@EXETYPE 136 
module-definition file@LIBRARY 139 
module-definition file@NAME 139 
nString resource See also STRINGTABLE 
resource statement, See also RCDATA 
resource statement 
nStyle 
control 

BUTTON class 83, 85, 87, 88, 89 

COMBOBOX class 91 

default@CHECKBOX statement 84 

default@COMBOBOX statement 92 

default@CTEXT statement 82 

default@DEFPUSHBUTTON statement 88 

default@EDITTEXT statement 90 

default@GROUPBOX statement 87 

default@ICON statement 92 

default@LISTBOX statement 86 

default@LTEXT statement 80 

default@PUSHBUTTON statement 85 

default@RADIOBUTTON statement 89 

default@RTEXT statement 81 

DS_ABSALIGN 74 

EDIT class 90 

LISTBOX class 86 

STATIC class 92 
window 

listing 75 

WS_BORDER 76, 86 

WS.CAPTION 76 

WS_CHILD 74, 76 

WS_CHILDWINDOW 76 

WS_CLIPCHILDREN 76 

WS_CLIPSIBLINGS 76 

WS_DISABLED 76, 85, 87, 88, 89, 90 

WS DLGFRAME 76 



WS_GROUP 76, 80, 81, 82, 83, 85, 88, 89, 

90 

WS_HSCROLL 76, 90 

WSJCONIC 76 

WS_MAXIMIZE 76 

WS_MAXIMIZEBOX 76 

WS_MIMIMIZE 76 

WS_MINIMIZEBOX 76 

WS_OVERLAPPED 77 

WS_OVERLAPPEDWINDOW 77 

WS_POPUP 77 

WS_POPUPWINDOW 77 

WS_SIZEBOX 77 

WS_SYSMENU 77 

WS_TABSTOP 77, 80, 81, 82, 83, 85, 87, 

88, 89, 90 

WS_THICKFRAME 77 

WS_VISIBLE 77 

WS_VSCROLL 77, 86, 90 
nSTYLE resource statement 

when #include directive required with 75 
nSTYLE statement 

DIALOG resource statement 74, 75 
nText control 
left-justified 80 
right-justified 81 
nWindow 
border 76 
child 76 
control 

user-defined 94 
creating 24, 75 
disabled 74, 76 
iconic 76 
overlapping 77 
pop-up 77 
size 76, 77 
style 

dialog box 75 
visible 77 
zoom 76 
nWindow style 
listing 75 
WS CHILD 74 
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ODA_DRAWENTIRE drawing action 37 
ODA_FOCUS drawing action 37 
ODA_SELECT drawing action 37 
ODDPARITY parity type 26 
ODS_CHECKED owner-draw control status 37 
ODS_DISABLED owner-draw control status 37 
ODS_FOCUS owner-draw control status 37 
ODS_GRAYED owner-draw control status 37 
ODS_SELECTED owner-draw control status 37 
ODT_BUTTON owner-draw control type 36, 47 
ODT_COMBOBOX owner-draw control type 

23, 28, 36, 47 
ODTJJSTBOX owner-draw control type 23, 

28, 36, 47 
ODT_MENU owner-draw control type 36, 47 
OFSTRUCT data structure 51 
ONE5STOPBITS stop-bits type 26 
ONESTOPBIT stop-bits type 26 
OR operator 72, 80, 81, 83, 85, 86, 87, 89, 90, 

91 



PAINTSTRUCT data structure 52 
PALETTEENTRY data structure 43, 52 
Parentheses ( ) 

as document convention 3 
PASSTHROUGH printer escape 185 
PC_EXPLICIT palette-entry option 53 
PC_NOCOLLAPSE palette-entry option 53 
PC_RESERVED palette-entry option 53 
PINT data type 9 
Plus (+) operator 80, 81, 82, 83, 85, 86, 87, 88, 

89, 90, 91, 92 
POINT data structure 54 
POPUP resource statement 70, 71, 72 
PRELOAD resource-compiler key word 62, 63, 

65, 66, 69, 73 
Printer driver 

initialization 29 
PROOF_QUALITY font quality 42 
PSTR data type 9 

PUSHBUTTON resource statement 84, 85 
PWORD data type 9 



Q 

QUERYESCSUPPORT printer escape 186 
Quotation marks 

double (\bcl70\ec) 70 

double (\bcl69\ec\bcl70\ec) 66, 67, 70, 78 
Quotation marks (\bcl69\ec \bcl70\ec) 

as document convention[Quotation marks ( ), 

as document convention] 3 



R2_BLACK raster drawing mode 144, 145 
R2_COPYPEN raster drawing mode 144, 145 
R2_MASKNOTPEN raster drawing mode 144, 

145 
R2_MASKPEN raster drawing mode 144, 145 
R2_MASKPENNOT raster drawing mode 144, 

145 
R2_MERGENOTPEN raster drawing mode 144, 

145 
R2_MERGEPEN raster drawing mode 744, 145 
R2_MERGEPENNOT raster drawing mode 144, 

145 
R2_NOP raster drawing mode 144, 145 
R2_NOT raster drawing mode 744, 745 
R2_NOTCOPYPEN raster drawing mode 744, 

745 
R2_NOTMASKPEN raster drawing mode 744, 

745 
R2_NOTMERGEPEN raster drawing mode 744, 

745 
R2_NOTXORPEN raster drawing mode 744, 

745 
R2_WHITE raster drawing mode 744, 745 
R2_XORPEN raster drawing mode 744, 745 
Radio-button control 88 
RADIOBUTTON resource statement 88, 89 
RCDATA resource statement 64, 65 
RECT data structure 54 
RESTORE_CTM printer escape 186 
RGBQUAD data structure 75, 55 
RGBTRIPLE data structure 12, 55 
RTEXT resource statement 80, 81 
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SBS_BOTTOM ALIGN control style 101 
SBS_HORZ control style 100 
SBS_LEFTALIGN control style 100 
SBS_RIGHT ALIGN control style 100 
SBS_SIZEBOX control style 101 
SBS_SIZEBOXBOTTOMRIGHTALIGN control 

style 101 
SBS_SIZEBOXTOPLEFTALIGN control style 

101 
SBSJTOPALIGN control style 101 
SBS_VERT control style 100 
Scroll bars 98, 100 
SCROLLBAR control class 95 
SCROLLBAR resource statement 93 
SEGMENTS module-definition statement 140 
SEGMENTS statement 133 
SET_ARC_DIRECTION printer escape 190 
SET_BACKGROUND_COLOR printer escape 

191 
SET_BOUNDS printer escape 191 
SET_CLIP_BOX printer escape 192 
SET_MIRROR_MODE printer escape 197 
SET_POLY_MODE printer escape 199 
SET_SCREEN_ANGLE printer escape 201 
SET_SPREAD printer escape 201 
SETABORTPROC printer escape 188 
SETALLJUSTVALUES printer escape 189 
SETCOLORTABLE printer escape 193 
SETCOPYCOUNT printer escape 194 
SETKERNTRACK printer escape 1 95 
SETLINECAP printer escape 196 
SETLINEJOIN printer escape 196 
SETMITERLIMIT printer escape 198 
SHIFT option 

ACCELERATORS resource statement 68 
short data type 9 

Single-line resource statement 61, 62 
Size-box control 77, 95 
Small capital letters 

as document convention 3 
SP_APPABORT escape error code 184, 185 
SP_ERROR escape error code 184, 185 
SP_OUTOFDISK escape error code 184, 185 
SP_OUTOFMEMORY escape error code 184, 

185 
SPJJSERABORT escape error code 184, 185 
SPACEPARITY parity type 26 



SS_BLACKFRAME control style 102 
SS_BLACKRECT control style 102 
SS_CENTER control style 101 
SS_GRAYFRAME control style 102 
SS_GRAYRECT control style 102 
SSJCON control style 92, 102 
SS_LEFT control style 101 
SS_LEFTNOWORDWRAP control style 101 
SS_NOPREFIX control style 102 
SS_RIGHT control style 101 
SS_SIMPLE control style 102 
SSJJSERITEM control style 102 
SS_WHITEFRAME control style 102 
SS_WHITERECT control style 102 
Stack 

local 141 
STACKSIZE module-definition statement 141 
STACKSIZE statement 133 
STARTDOC printer escape 202 
STATIC control class 95 
String resource 66 

STRINGTABLE resource statement 65, 66 
STUB module-definition statement 141 
STUB statement 133 
STYLE resource statement 75 
STYLE statement 

listing window style 75 
System-menu box 77 



Tab stop 95 
Table 

handle 38 
Template 

DIALOG 73 
TEXTMETRIC data structure 56 
Title bar 76, 77 

TRANSFORM_CTM printer escape 203 
TranslateAccelerator function 67 
TWOSTOPBITS stop-bits type 26 
Types 

data 7, 8, 9 
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User-defined control window 94 
User-defined resource 63 
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User-defined resource statement 63, 64 

V 

Variable 

environmental 
INCLUDE 103 
Vertical bar ( I ) 

as document convention 3 
Virtual-key character 67 
void data type 9 

w 

WINDOWS.H initialization file 75 
WM_COMMAND message 20 
WM_COMMAND message message 67 
WM_COMPAREITEM message 22 
WM_DDE_ACK message 209 
WM_DDE_ADVISE message 21 1 
WM_DDE_DATA message 213 
WM_DDE_EXECUTE message 214 
WM_DDE_INITIATE message 216 
WM_DDE_POKE message 217 
WM_DDE_REQUEST message 218 
WM_DDE_TERMINATE message 219 
WM_DDE_UNADVISE message 219 
WM_DELETEITEM message 28 
WM_DRAWITEM message 36 
WM_ENTERIDLE message 33 
WM_MEASUREITEM message 46 
WM_SETFONT message 33 
WM_SVSCOMMAND message 67 



WM_SYSMENU window style 33 
WNDCLASS data structure 58 
WORD data type 9 
Wordwrap 98 

WS_BORDER window style 76, 86, 91 
WS_CAPTION window style 33, 76 
WS_CHILD window style 74, 76 
WS_CHILDWINDOW window style 76 
WS_CLIPCHILDREN window style 76 
WS_CLIPSIBLINGS window style 76 
WS_DISABLED window style 76, 85, 87, 88, 

89,90 
WS_DLGFRAME window style 76 
WS_GROUP control style 76, 80, 81, 82, 83, 85, 

88, 89, 90 
WS_HSCROLL window style 46, 76, 90 
WSJCONIC window style 76 
WS_MAXIMIZE window style 46, 76 
WS_MAXIMIZEBOX window style 76 
WS_MINIMIZE window style 46, 76 
WS_MINIMIZEBOX window style 76 
WS_OVERLAPPED window style 77 
WS_OVERLAPPEDWINDOW window style 77 
WS_POPUP window style 77 
WS_POPUPWINDOW window style 77 
WS_SLZEBOX window style 77 
WS_SYSMENU window style 76, 77 
WSJTABSTOP window style 77, 80, 81, 82, 83, 

85, 87, 88, 89, 90 
WSJTHICKFRAME window style 77 
WS_VISIBLE window style 77 
WSJ/SCROLL window style 46, 77, 86, 90, 91 
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